@pulsesync/addon-sdk 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +81 -74
  2. package/package.json +4 -2
package/README.md CHANGED
@@ -1,119 +1,126 @@
1
- # PulseSync Addon SDK
1
+ # @pulsesync/addon-sdk
2
2
 
3
- Публичный TypeScript/React SDK для аддонов, которые запускаются через PulseSync WebHost.
3
+ [![npm](https://img.shields.io/npm/v/@pulsesync/addon-sdk)](https://www.npmjs.com/package/@pulsesync/addon-sdk)
4
+ [![license](https://img.shields.io/npm/l/@pulsesync/addon-sdk)](https://www.gnu.org/licenses/gpl-3.0.html)
4
5
 
5
- WebHost владеет единственным React root и предоставляет аддонам React `19.2.4`. Аддон экспортирует компоненты и не вызывает `createRoot()` самостоятельно.
6
+ Официальный SDK для React-аддонов PulseSync WebHost.
7
+
8
+ - [Шаблон аддона](https://github.com/PulseSync-LLC/PulseSync-ExampleAddon)
9
+ - [PulseSync](https://pulsesync.dev)
10
+
11
+ > SDK находится в preview. До версии `1.0.0` API может меняться между minor-релизами.
6
12
 
7
13
  ## Установка
8
14
 
9
15
  ```bash
10
16
  npm install @pulsesync/addon-sdk react@19.2.4
11
- npm install -D vite @vitejs/plugin-react typescript @types/react
17
+ npm install --save-dev vite @vitejs/plugin-react typescript @types/react
12
18
  ```
13
19
 
14
- ## Обычный компонент
20
+ React предоставляет WebHost. Не добавляйте `react-dom` в аддон и не вызывайте `createRoot()`.
21
+
22
+ ## Аддон
15
23
 
16
24
  ```tsx
17
- import { defineAddon } from '@pulsesync/addon-sdk'
25
+ import { defineAddon, type PulseSyncAddonComponentProps } from '@pulsesync/addon-sdk'
18
26
 
19
- function App() {
20
- return <div>PulseSync addon</div>
27
+ function PlayerButton({ api }: PulseSyncAddonComponentProps) {
28
+ return <button onClick={() => api.pulsesyncApi?.togglePlayPause()}>Play / Pause</button>
21
29
  }
22
30
 
23
31
  export default defineAddon({
24
- id: 'example-addon',
25
- name: 'Example Addon',
26
- component: App,
27
- })
28
- ```
29
-
30
- ## Стандартные точки интерфейса
31
-
32
- Имена slots задаёт WebHost. Аддон только отдаёт React-компонент для нужной точки.
33
-
34
- ```tsx
35
- export default defineAddon({
36
- id: 'player-actions',
32
+ id: 'player-button',
37
33
  slots: {
38
34
  playerBarButton: PlayerButton,
39
- contextMenuActions: ContextMenuActions,
40
35
  },
41
36
  })
42
37
  ```
43
38
 
44
- ## Произвольная точка
39
+ `id` должен быть постоянным: по нему WebHost хранит состояние и настройки аддона.
45
40
 
46
- Если стандартного slot нет, автор может указать DOM-цель самостоятельно.
41
+ ## Настройки
47
42
 
48
- ```tsx
49
- export default defineAddon({
50
- id: 'custom-target',
51
- mounts: [
52
- {
53
- target: '[data-test-id="PLAYERBAR_DESKTOP"]',
54
- component: PlayerButton,
43
+ ```ts
44
+ // src/settings.ts
45
+ import { defineSettings } from '@pulsesync/addon-sdk'
46
+
47
+ export const settings = defineSettings(
48
+ {
49
+ enabled: {
50
+ type: 'boolean',
51
+ name: 'Включить аддон',
52
+ default: true,
53
+ },
54
+ accentColor: {
55
+ type: 'color',
56
+ name: 'Цвет кнопки',
57
+ default: '#ffdb4d',
55
58
  },
56
- ],
57
- })
58
- ```
59
-
60
- `target` также принимает `Element`, функцию `() => Element | null`, `{ selector }` или `{ slot }`.
61
-
62
- ## Lifecycle
63
-
64
- ```tsx
65
- export default defineAddon({
66
- id: 'lifecycle-example',
67
- start(api) {
68
- api.logger.info('Started')
69
- return () => api.logger.info('Start cleanup')
70
- },
71
- stop(api) {
72
- api.logger.info('Stopped')
73
59
  },
74
- })
60
+ { title: 'Основные' },
61
+ )
75
62
  ```
76
63
 
77
- ## Настройки
78
-
79
- Схема живёт рядом с кодом аддона и остаётся типизированной:
80
-
81
64
  ```tsx
82
- import { defineSettings, type PulseSyncAddonComponentProps } from '@pulsesync/addon-sdk'
65
+ import { settings } from './settings'
83
66
 
84
- export const settings = defineSettings({
85
- enabled: {
86
- type: 'boolean',
87
- name: 'Включить аддон',
88
- default: true,
89
- },
90
- })
67
+ function PlayerButton({ api }: PulseSyncAddonComponentProps) {
68
+ const { accentColor, enabled } = settings.use(api)
91
69
 
92
- function App({ api }: PulseSyncAddonComponentProps) {
93
- const { enabled } = settings.use(api)
94
- return enabled ? <div>PulseSync addon</div> : null
70
+ if (!enabled) return null
71
+ return <button style={{ color: accentColor }}>Play / Pause</button>
95
72
  }
96
73
  ```
97
74
 
98
- Передай `settings` в `pulseSyncAddon({ manifest, settings })`. Сборщик запишет схему в `metadata.json`; отдельный `handleEvents.json` для WebHost-аддона не нужен.
75
+ Передайте `settings` сборщику. Схема попадёт в `metadata.json`, а пользовательские значения PulseSync сохранит отдельно. `handleEvents.json` WebHost-аддону не нужен.
99
76
 
100
- ## Vite
77
+ Поддерживаемые типы: `boolean`, `number`, `select`, `text`, `color`, `file`.
78
+
79
+ ## Сборка
101
80
 
102
81
  ```ts
82
+ // vite.config.ts
103
83
  import react from '@vitejs/plugin-react'
104
84
  import { defineConfig } from 'vite'
105
85
  import { defineAddonManifest, pulseSyncAddon } from '@pulsesync/addon-sdk/vite'
106
86
 
107
- const manifest = defineAddonManifest({
108
- id: 'example-addon',
109
- directoryName: 'example-addon',
110
- name: 'Example Addon',
111
- version: '0.1.0',
112
- })
87
+ import addonConfig from './addon.config.mjs'
88
+ import { settings } from './src/settings.ts'
113
89
 
114
90
  export default defineConfig({
115
- plugins: [react(), pulseSyncAddon({ manifest })],
91
+ plugins: [
92
+ react(),
93
+ pulseSyncAddon({
94
+ manifest: defineAddonManifest(addonConfig),
95
+ settings,
96
+ }),
97
+ ],
116
98
  })
117
99
  ```
118
100
 
119
- Плагин собирает `script.js`, `script.css` и `metadata.json`, помечает аддон как `web-addon`, исключает React из бандла и запрещает импорт `react-dom`.
101
+ Сборка создаёт папку `dist/<directoryName>`:
102
+
103
+ ```text
104
+ metadata.json
105
+ script.css
106
+ script.js
107
+ ```
108
+
109
+ React и JSX runtime остаются внешними зависимостями и берутся из WebHost.
110
+
111
+ ## Экспорты
112
+
113
+ | Импорт | Назначение |
114
+ | --- | --- |
115
+ | `@pulsesync/addon-sdk` | `defineAddon`, `defineSettings`, runtime-типы |
116
+ | `@pulsesync/addon-sdk/vite` | `pulseSyncAddon`, `defineAddonManifest` |
117
+
118
+ ## Требования
119
+
120
+ - Node.js 20 или новее;
121
+ - React `19.2.4`;
122
+ - PulseSync WebHost API v1.
123
+
124
+ ## Лицензия
125
+
126
+ GPL-3.0-or-later
package/package.json CHANGED
@@ -1,7 +1,9 @@
1
1
  {
2
2
  "name": "@pulsesync/addon-sdk",
3
- "version": "0.1.0",
4
- "description": "Public SDK for building PulseSync WebHost addons",
3
+ "version": "0.1.1",
4
+ "description": "Official SDK for PulseSync WebHost addons",
5
+ "author": "PulseSync <contact@pulsesync.dev>",
6
+ "homepage": "https://pulsesync.dev",
5
7
  "license": "GPL-3.0-or-later",
6
8
  "type": "module",
7
9
  "sideEffects": false,