npm package: @fastwork/xosmoz-svelte
Description: Svelte 5 components for Xosmoz design system
Latest version: 2.0.0

# @fastwork/xosmoz-svelte

Svelte 5 components for the Xosmoz design system.

## Installation

```bash
npm install @fastwork/xosmoz-svelte @fastwork/xosmoz-theme @fastwork/xosmoz-css
# or
yarn add @fastwork/xosmoz-svelte @fastwork/xosmoz-theme @fastwork/xosmoz-css
```

## Requirements

| Package                  | Minimum Version |
| ------------------------ | --------------- |
| `svelte`                 | `^5.0.0`        |
| `@fastwork/xosmoz-theme` | `*`             |
| `@fastwork/xosmoz-css`   | `*`             |

## Usage

### 1. Import Styles

Add the required CSS to your app entry point or layout:

```svelte
<!-- In your +layout.svelte or app entry -->
<script>
	import '@fastwork/xosmoz-svelte/styles.css'
</script>
```

Or import styles individually for more control:

```ts
import '@fastwork/xosmoz-theme/base.css'
import '@fastwork/xosmoz-theme/themes.css'
import '@fastwork/xosmoz-css/component.css'
```

### 2. Set Theme

Add a `data-theme` attribute to enable theming:

```html
<html data-theme="light">
	<!-- or "dark" -->
</html>
```

### 3. Use Components

```svelte
<script>
	import { Button } from '@fastwork/xosmoz-svelte'
</script>

<Button variant="primary" size="medium">Click me</Button>
```

## Components

| Component                         | Description                                                            |
| --------------------------------- | ---------------------------------------------------------------------- |
| `Badge`                           | Labels, tags, and status indicators (solid, soft, soft-solid variants) |
| `BlankSlate`                      | Empty state with optional image, heading, description                  |
| `Button`                          | Button with 28 variants, 3 sizes, icons, loading state                 |
| `ButtonGroup` + `ButtonGroupItem` | Grouped toggle buttons (compound, context-based)                       |
| `Checkbox`                        | Checkbox with indeterminate state support                              |
| `Chip`                            | Selectable chip/tag                                                    |
| `Input`                           | Text input with label, prefix/suffix, password toggle                  |
| `Link`                            | Styled anchor with variants and external link support                  |
| `Loader`                          | Spinner (dot animation or Fastwork logo)                               |
| `Message`                         | Alert/notification message with icon support                           |
| `Radio`                           | Radio input with label                                                 |
| `RadioButton`                     | Styled radio button alternative                                        |
| `Select`                          | Select dropdown with label and validation states                       |
| `Switch`                          | Toggle switch in 3 sizes                                               |
| `TabList` + `TabListItem`         | Tab navigation (compound, context-based)                               |
| `Textarea`                        | Textarea with char count and validation states                         |

### Button Example

```svelte
<script>
	import { Button } from '@fastwork/xosmoz-svelte'
</script>

<!-- Solid variants -->
<Button variant="primary">Primary</Button>
<Button variant="danger">Danger</Button>
<Button variant="success">Success</Button>

<!-- Soft / Outline / Ghost -->
<Button variant="primary-soft">Primary Soft</Button>
<Button variant="primary-outline">Primary Outline</Button>
<Button variant="primary-ghost">Primary Ghost</Button>

<!-- Sizes -->
<Button size="small">Small</Button>
<Button size="medium">Medium</Button>
<Button size="large">Large</Button>

<!-- States -->
<Button isLoading>Loading</Button>
<Button disabled>Disabled</Button>
<Button isFluid>Full Width</Button>

<!-- Icons -->
<Button leftIconClass="fas fa-plus">Add</Button>
```

### Form Controls Example

```svelte
<script>
	import {
		Input,
		Checkbox,
		Switch,
		Select,
		Textarea,
	} from '@fastwork/xosmoz-svelte'

	let email = $state('')
	let agreed = $state(false)
	let notifications = $state(true)
	let country = $state('')
	let bio = $state('')
</script>

<Input label="Email" bind:value={email} variant="default" />
<Input label="Password" type="password" bind:value={email} />
<Input label="Website" prefix="https://" bind:value={email} />

<Checkbox id="terms" label="I agree to the terms" bind:checked={agreed} />
<Switch id="notif" label="Enable notifications" bind:checked={notifications} />

<Select label="Country" bind:value={country}>
	<option value="th">Thailand</option>
	<option value="us">United States</option>
</Select>

<Textarea label="Bio" maxlength={200} bind:value={bio} />
```

### Compound Components Example

```svelte
<script>
	import {
		TabList,
		TabListItem,
		ButtonGroup,
		ButtonGroupItem,
	} from '@fastwork/xosmoz-svelte'

	let tab = $state('overview')
	let view = $state('list')
</script>

<TabList bind:value={tab}>
	<TabListItem value="overview">Overview</TabListItem>
	<TabListItem value="details">Details</TabListItem>
	<TabListItem value="reviews">Reviews</TabListItem>
</TabList>

<ButtonGroup bind:value={view}>
	<ButtonGroupItem value="list" iconClass="fas fa-list">List</ButtonGroupItem>
	<ButtonGroupItem value="grid" iconClass="fas fa-th">Grid</ButtonGroupItem>
</ButtonGroup>
```

## Development

### Prerequisites

From the monorepo root:

```bash
yarn install
```

### Build

```bash
# Build svelte package
make build-svelte

# Or from package dir
cd packages/xosmoz-svelte && yarn build:package
```

### Storybook

```bash
# From monorepo root (cleans cache, builds deps first)
make storybook

# Or directly
yarn storybook
```

Opens at `http://localhost:6006`

### Build Storybook

```bash
make storybook-build
```

### Publish

```bash
# Interactive local publish
make publish-svelte

# Or via GitHub Actions: "Publish Svelte Package" workflow
```

### Project Structure

```
packages/xosmoz-svelte/
  src/
    lib/
      components/
        badge/          Badge.svelte, Badge.stories.ts, BadgeShowcase.svelte
        blank-slate/    ...
        button/         ...
        button-group/   ButtonGroup.svelte, ButtonGroupItem.svelte
        checkbox/       ...
        chip/           ...
        input/          ...
        link/           ...
        loader/         ...
        message/        ...
        radio/          ...
        radio-button/   ...
        select/         ...
        switch/         ...
        tab-list/       TabList.svelte, TabListItem.svelte
        textarea/       ...
        examples/       11 example apps (CactusStore, CryptoWallet, etc.)
      docs/
        foundation/     Colors, Typography, Themes, BoxShadows, KitchenSink
      styles/
        _helpers.scss   SCSS utilities (toRem, toEm)
      utils/
        colorCalculations.ts
        themeDetection.ts
        clipboard.ts
      index.ts          Barrel exports
  .storybook/           Storybook config
  svelte.config.js
  vite.config.ts
  package.json
```

## License

MIT