# @sky.ui/core

Lit-based web components for Sky UI. Use tags such as `<sky-button>` and `<sky-card>` in any framework, or import components directly for tree-shaken bundles.

## Install

```bash
npm install "@sky.ui/core"
```

> Quote scoped names (`"@sky.ui/…"`) — required in PowerShell. See [powershell-scoped-packages.md](https://gitlab.com/sky_ui/sky-ui/-/blob/main/docs/powershell-scoped-packages.md).

Peer dependencies (install for the components you use): `lit`, `@lit-labs/motion`, `@lit-labs/virtualizer`, `@lit/context`, `d3`, `three`. Runtime peers are required (not optional in `peerDependenciesMeta`) so Vite/Nuxt do not stub missing peers as empty modules.

## Quick start

```js
import { SkyButton, SkyCard } from '@sky.ui/core';
```

Register or render components in your app. In HTML:

```html
<sky-button label="Save"></sky-button>
```

Only the components you import are included in production bundles when your bundler tree-shakes ESM.

## Tree-shaking

- Published as **ESM** with **one file per component** (`preserveModules`).
- Import from the package root or per-component paths (`@sky.ui/core/sky-button`).
- Use a **production build** (`vite build`, `nuxt build`, webpack production) so unused exports are dropped. Dev servers may include more for faster HMR.

## Vite

```js
import { SkyUIMainVitePlugin } from '@sky.ui/core/vite';

export default {
  plugins: [
    // Vue: auto-import <SkyButton> / <sky-button> (requires unplugin-vue-components)
    SkyUIMainVitePlugin(), // or SkyUIMainVitePlugin({ mode: 'vue' })

    // Framework-less HTML/JS: scan for <sky-*> and inject imports
    // SkyUIMainVitePlugin({ mode: 'auto-import' })

    // Whole library: SkyUIMainVitePlugin({ mode: 'auto-import', treeShake: false })
  ],
};
```

**Vue auto-import:** install `unplugin-vue-components`. Options include `resolverOptions`, `dts`, and `componentsOptions`.

**Resolver only:** `import { SkyUIMainResolver } from '@sky.ui/core/auto-import'`.

For Vue SFC wrappers or React, use `@sky.ui/vue` or `@sky.ui/react` instead.

## Webpack and Rollup

**Webpack**

```js
import { SkyUIMainWebpackPlugin } from '@sky.ui/core/webpack';

export default {
  plugins: [SkyUIMainWebpackPlugin()],
};
```

**Rollup** (returns an array — spread into `plugins`):

```js
import { SkyUIMainRollupPlugin } from '@sky.ui/core/rollup';

export default {
  plugins: [
    ...SkyUIMainRollupPlugin(),
    // auto-import: ...SkyUIMainRollupPlugin({ mode: 'auto-import', entryHtml: 'index.html' }),
  ],
};
```

## Manual and full-library imports

```js
import { SkyButton, SkyCard } from '@sky.ui/core';
import '@sky.ui/core/sky-button';

// Entire catalog
import '@sky.ui/core/all';
import * as Sky from '@sky.ui/core';
```

## Custom Elements Manifest

After building from source, component metadata is available at `@sky.ui/core/custom-elements.json`.

## Related packages

| Package | Use when |
|---------|----------|
| [`@sky.ui/vue`](https://www.npmjs.com/package/@sky.ui/vue) | Vue 3 SFC wrappers |
| [`@sky.ui/react`](https://www.npmjs.com/package/@sky.ui/react) | React wrappers |
| [`@sky.ui/utils`](https://www.npmjs.com/package/@sky.ui/utils) | Utility CSS and PostCSS JIT |
| [`@sky.ui/reactivity`](https://www.npmjs.com/package/@sky.ui/reactivity) | Lightweight reactivity and template directives |
| [`@sky.ui.pro/core`](https://www.npmjs.com/package/@sky.ui.pro/core) | Pro-tier components |

## Editor support

Install the **Sky UI Components** VS Code extension for completions, hover docs, and validation in HTML, Vue, and JSX.

## License

[Sky UI Free EULA](https://unpkg.com/@sky.ui/core/LICENSE.md) — proprietary; not open source.