@luckylu.cy/sync-todo-overlay 0.0.0-stage → 1.0.0
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.
- package/README.md +240 -2
- package/package.json +73 -4
package/README.md
CHANGED
|
@@ -1,3 +1,241 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Sync Todo overlay
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Add a floating quick-add button to a web page. The editor uses the first nonempty line as the todo title and the remaining lines as the description. Hashtags can be completed from the configured account and are sent as todo tags.
|
|
4
|
+
|
|
5
|
+
Create an embed key in Sync Todo under **Settings → Embed keys**. The page shows the key and a paste-ready script once. The server URL is the Sync Todo web origin or its `/api` URL.
|
|
6
|
+
|
|
7
|
+
Anyone who can read the page source can use an embedded key to add todos and read the account’s writable list names and tag names. Keep keys in private pages when the names are private, and revoke keys in Settings when a page should lose access.
|
|
8
|
+
|
|
9
|
+
The standalone script includes Vue and is <!-- bundle-size -->43.8 KiB gzip<!-- /bundle-size -->. Vue consumers use their existing Vue 3.5 runtime. The React wrapper supports React 18 and 19.
|
|
10
|
+
|
|
11
|
+
## 1. Vue component
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
yarn add @luckylu.cy/sync-todo-overlay
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```vue
|
|
18
|
+
<script setup lang="ts">
|
|
19
|
+
import { ref } from 'vue'
|
|
20
|
+
import Overlay from '@luckylu.cy/sync-todo-overlay/vue'
|
|
21
|
+
import '@luckylu.cy/sync-todo-overlay/style'
|
|
22
|
+
|
|
23
|
+
const open = ref(false)
|
|
24
|
+
</script>
|
|
25
|
+
|
|
26
|
+
<template>
|
|
27
|
+
<button type="button" @click="open = true">Add to my list</button>
|
|
28
|
+
<Overlay
|
|
29
|
+
v-model:open="open"
|
|
30
|
+
url="https://todos.example"
|
|
31
|
+
token="YOUR_EMBED_KEY"
|
|
32
|
+
:show-button="false"
|
|
33
|
+
@created="todo => console.log(todo.uid)"
|
|
34
|
+
/>
|
|
35
|
+
</template>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The Vue component renders into the host DOM. Import `/style` for the overlay and editor styles. For server-rendered pages, mount the interactive overlay within the framework’s client boundary.
|
|
39
|
+
|
|
40
|
+
## 2. TypeScript and CommonJS
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { register, SyncTodoOverlayElement } from '@luckylu.cy/sync-todo-overlay'
|
|
44
|
+
|
|
45
|
+
register()
|
|
46
|
+
const overlay = new SyncTodoOverlayElement({
|
|
47
|
+
url: 'https://todos.example',
|
|
48
|
+
token: 'YOUR_EMBED_KEY',
|
|
49
|
+
calendarId: 7,
|
|
50
|
+
})
|
|
51
|
+
overlay.addEventListener('submit', event => {
|
|
52
|
+
console.log(event.detail.summary)
|
|
53
|
+
})
|
|
54
|
+
document.body.append(overlay)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The package root also supports `require('@luckylu.cy/sync-todo-overlay')` and ships CommonJS declarations. `@luckylu.cy/sync-todo-overlay/cjs` explicitly selects that build.
|
|
58
|
+
|
|
59
|
+
## 3. Vanilla script tag
|
|
60
|
+
|
|
61
|
+
```html
|
|
62
|
+
<script
|
|
63
|
+
src="https://todos.example/embed/todo-overlay.js"
|
|
64
|
+
data-prop-url="https://todos.example"
|
|
65
|
+
data-prop-token="YOUR_EMBED_KEY"
|
|
66
|
+
data-prop-tag="Website"
|
|
67
|
+
></script>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Use the kebab-case `data-prop-*` spelling for primitive props. With any of these attributes present, the script appends an overlay when the document body exists. Add `data-prop-position="left"` to move its button.
|
|
71
|
+
|
|
72
|
+
## 4. HTML custom element
|
|
73
|
+
|
|
74
|
+
```html
|
|
75
|
+
<script src="https://todos.example/embed/todo-overlay.js"></script>
|
|
76
|
+
<sync-todo-overlay
|
|
77
|
+
url="https://todos.example"
|
|
78
|
+
token="YOUR_EMBED_KEY"
|
|
79
|
+
calendar-id="7"
|
|
80
|
+
></sync-todo-overlay>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The script registers the tag. Alternatively, import `register()` from the ESM entry and call it yourself. The ESM and CommonJS imports have no registration side effects. Use `register('my-quick-todo')` for a different tag name.
|
|
84
|
+
|
|
85
|
+
Set object props as DOM properties in your page’s JavaScript, for example `document.querySelector('sync-todo-overlay').texts = { add: 'Save todo' }`. Use `addEventListener` for custom events. Install listeners before the element is upgraded or inserted to receive the startup events.
|
|
86
|
+
|
|
87
|
+
## 5. React wrapper
|
|
88
|
+
|
|
89
|
+
```tsx
|
|
90
|
+
import { useRef } from 'react'
|
|
91
|
+
import { SyncTodoOverlay, type OverlayActions } from '@luckylu.cy/sync-todo-overlay/react'
|
|
92
|
+
|
|
93
|
+
export function QuickAdd() {
|
|
94
|
+
const overlay = useRef<OverlayActions>(null)
|
|
95
|
+
return (
|
|
96
|
+
<>
|
|
97
|
+
<button onClick={() => overlay.current?.show()}>Quick add</button>
|
|
98
|
+
<SyncTodoOverlay
|
|
99
|
+
ref={overlay}
|
|
100
|
+
showButton={false}
|
|
101
|
+
url="https://todos.example"
|
|
102
|
+
token="YOUR_EMBED_KEY"
|
|
103
|
+
onCreated={todo => console.log(todo.uid)}
|
|
104
|
+
onSubmit={(todo, event) => {
|
|
105
|
+
if (!todo.summary.trim()) event.preventDefault()
|
|
106
|
+
}}
|
|
107
|
+
/>
|
|
108
|
+
</>
|
|
109
|
+
)
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Callbacks use the names listed in the event table with the `on` prefix. They receive the detail and the DOM event. For controlled `open`, update the state in `onOpen` and `onClose`.
|
|
114
|
+
|
|
115
|
+
## 6. Bare React 18 tag
|
|
116
|
+
|
|
117
|
+
```tsx
|
|
118
|
+
import { useLayoutEffect, useRef } from 'react'
|
|
119
|
+
import { register, type SyncTodoOverlayElement } from '@luckylu.cy/sync-todo-overlay'
|
|
120
|
+
import type {} from '@luckylu.cy/sync-todo-overlay/react'
|
|
121
|
+
|
|
122
|
+
export function QuickAdd() {
|
|
123
|
+
const overlay = useRef<SyncTodoOverlayElement>(null)
|
|
124
|
+
useLayoutEffect(() => {
|
|
125
|
+
const element = overlay.current!
|
|
126
|
+
const created = (event: CustomEvent<{ uid: string }>) => console.log(event.detail.uid)
|
|
127
|
+
element.url = 'https://todos.example'
|
|
128
|
+
element.token = 'YOUR_EMBED_KEY'
|
|
129
|
+
element.texts = { add: 'Save todo' }
|
|
130
|
+
element.addEventListener('created', created)
|
|
131
|
+
register()
|
|
132
|
+
return () => element.removeEventListener('created', created)
|
|
133
|
+
}, [])
|
|
134
|
+
return <sync-todo-overlay ref={overlay} />
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## 7. Bare React 19 tag
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
import { register } from '@luckylu.cy/sync-todo-overlay'
|
|
142
|
+
import type {} from '@luckylu.cy/sync-todo-overlay/react'
|
|
143
|
+
|
|
144
|
+
register()
|
|
145
|
+
|
|
146
|
+
export function QuickAdd() {
|
|
147
|
+
return (
|
|
148
|
+
<sync-todo-overlay
|
|
149
|
+
url="https://todos.example"
|
|
150
|
+
token="YOUR_EMBED_KEY"
|
|
151
|
+
texts={{ add: 'Save todo' }}
|
|
152
|
+
oncreated={event => console.log(event.detail.uid)}
|
|
153
|
+
/>
|
|
154
|
+
)
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The typed native handlers use the exact event name after `on`, including dashes in names such as `onsettings-load`.
|
|
159
|
+
|
|
160
|
+
## Props and methods
|
|
161
|
+
|
|
162
|
+
| Property | HTML attribute | Default and behavior |
|
|
163
|
+
| --- | --- | --- |
|
|
164
|
+
| `url` | `url` | Saved value or blank. Absolute HTTP(S) server URL. The overlay appends `/api` if needed. |
|
|
165
|
+
| `token` | `token` | Saved value or blank. Embed key. |
|
|
166
|
+
| `calendarId` | `calendar-id` | Saved value or `null` to use the default writable list. |
|
|
167
|
+
| `tag` | `tag` | Saved value or `null` for no preset tag. |
|
|
168
|
+
| `open` | `open` | Controls whether the sheet is open. |
|
|
169
|
+
| `defaultOpen` | `default-open` | `false`. Starts open when `open` is omitted. |
|
|
170
|
+
| `position` | `position` | `right`. Also accepts `left`. |
|
|
171
|
+
| `showButton` | `show-button` | `true`. Shows the floating launcher. |
|
|
172
|
+
| `showSettings` | `show-settings` | `true`. Shows the gear inside the overlay. |
|
|
173
|
+
| `autoClose` | `auto-close` | `true`. Closes after creation. |
|
|
174
|
+
| `persist` | `persist` | `true`. Saves settings to the host’s local storage. |
|
|
175
|
+
| `storageKey` | `storage-key` | `sync-todo-overlay`. Use distinct keys for independent overlays on the same origin. |
|
|
176
|
+
| `disabled` | `disabled` | `false`. Disables opening and submitting. |
|
|
177
|
+
| `lang` | `lang` | Uses the host’s HTML language, then the browser language. Supports `en`, `de`, `fr`, `es`, `it`, and `ru`, with fallback to English. |
|
|
178
|
+
| `texts` | Property only | Partial `OverlayTexts` translation overrides. |
|
|
179
|
+
| `settings` | Property only | A partial `OverlaySettings` object. |
|
|
180
|
+
| `nonce` | `nonce` | CSP nonce for the shadow style elements. Set before the element connects. |
|
|
181
|
+
|
|
182
|
+
Explicit props take precedence over `settings`, which takes precedence over saved values. Settings fields supplied by the host are locked. Use the DOM property to specify an explicit `null` calendar or tag. A boolean HTML attribute can use the empty string for true or `"false"` for false.
|
|
183
|
+
|
|
184
|
+
Every integration exposes `show()`, `hide()`, `toggle()`, and `openSettings()`. For Vue use a template ref. For React use the wrapper’s forwarded ref.
|
|
185
|
+
|
|
186
|
+
## Events
|
|
187
|
+
|
|
188
|
+
DOM events bubble and cross the shadow boundary. The Vue component emits the same names, along with `update:open` for `v-model:open`. Vue supplies the native cancelable event as the second argument for `submit`, `settings-load`, and `settings-save`.
|
|
189
|
+
|
|
190
|
+
| DOM event | React callback | Detail |
|
|
191
|
+
| --- | --- | --- |
|
|
192
|
+
| `ready` | `onReady` | `{}` after settings load |
|
|
193
|
+
| `open` | `onOpen` | `{}` |
|
|
194
|
+
| `close` | `onClose` | `{}` |
|
|
195
|
+
| `cancel` | `onCancel` | `{}` when the sheet closes without a creation |
|
|
196
|
+
| `submit` | `onSubmit` | `{ summary, description, tag, tags, calendarId }`. Prevent the default to handle submission yourself. |
|
|
197
|
+
| `created` | `onCreated` | `{ uid, summary }` |
|
|
198
|
+
| `error` | `onError` | `{ message, status }`. Status can be null for network failures. |
|
|
199
|
+
| `settings-open` | `onSettingsOpen` | `{}` |
|
|
200
|
+
| `settings-close` | `onSettingsClose` | `{}` |
|
|
201
|
+
| `settings-change` | `onSettingsChange` | `{ values }` containing the effective configuration |
|
|
202
|
+
| `settings-load` | `onSettingsLoad` | `{ provide(values) }`. Call `provide` synchronously and prevent the default to skip local storage. |
|
|
203
|
+
| `settings-save` | `onSettingsSave` | `{ values }` containing the saved user-supplied fields. Prevent the default to store them yourself. |
|
|
204
|
+
| `calendars-loaded` | `onCalendarsLoaded` | `{ calendars }`. Each calendar has `id`, `name`, `account`, and `is_default`. |
|
|
205
|
+
|
|
206
|
+
For example, a host can provide settings from memory and receive subsequent edits.
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
let settings = { url: 'https://todos.example', token: 'YOUR_EMBED_KEY' }
|
|
210
|
+
overlay.addEventListener('settings-load', event => {
|
|
211
|
+
event.detail.provide(settings)
|
|
212
|
+
event.preventDefault()
|
|
213
|
+
})
|
|
214
|
+
overlay.addEventListener('settings-save', event => {
|
|
215
|
+
settings = { ...settings, ...event.detail.values }
|
|
216
|
+
event.preventDefault()
|
|
217
|
+
})
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
`resolveTexts(lang, overrides)`, `OverlayTexts`, `OverlaySettings`, `OverlayProps`, and each event detail type are available from the package root.
|
|
221
|
+
|
|
222
|
+
## Theme and CSP
|
|
223
|
+
|
|
224
|
+
Set CSS variables on the custom element or an ancestor. They inherit into the shadow root and also apply to the light-DOM Vue component.
|
|
225
|
+
|
|
226
|
+
| Variables | Controls |
|
|
227
|
+
| --- | --- |
|
|
228
|
+
| `--sync-todo-bg`, `--sync-todo-fg`, `--sync-todo-hint`, `--sync-todo-border` | Background, text, muted text, and borders |
|
|
229
|
+
| `--sync-todo-accent`, `--sync-todo-accent-fg`, `--sync-todo-chip-bg`, `--sync-todo-danger` | Buttons, contrast text, chips, and errors |
|
|
230
|
+
| `--sync-todo-radius`, `--sync-todo-font`, `--sync-todo-z-index`, `--sync-todo-shadow` | Corners, font, overlay depth, and shadow |
|
|
231
|
+
|
|
232
|
+
The defaults read Telegram theme variables when present and follow the system color scheme otherwise.
|
|
233
|
+
|
|
234
|
+
Allow the script origin in `script-src` and the Sync Todo server in `connect-src`. For a nonce-based `style-src`, pass the matching nonce as `data-prop-nonce` on the script tag, `nonce` on the custom element, or the `nonce` prop on the React wrapper. The script tag also uses its own `nonce` when no style nonce is specified.
|
|
235
|
+
|
|
236
|
+
## Build and release
|
|
237
|
+
|
|
238
|
+
From the Mini App’s `frontend/`, `yarn build:embed` creates the installable package files in `embed/dist/` and the nginx assets in `dist-embed/`. `yarn test:embed` type-checks and builds the examples and runs them with Playwright against a stub API.
|
|
239
|
+
|
|
240
|
+
On a push to `deploy4`, the monorepo workflow reads the base version from `package.json` and appends `-YYYY.M.D-H.M.S-build<number>-<hash>` using the commit's UTC timestamp, the workflow run number, and the first six characters of the commit SHA. Each leading zero in the hash becomes `O`. The workflow creates `embed-v<version>` and writes that version into the package manifest before building, testing, and publishing `@luckylu.cy/sync-todo-overlay`.
|
|
241
|
+
A manual workflow run with `dry_run` builds and previews the package. Real publishes use provenance with either an npm trusted publisher for `embed-publish.yml` or a granular `NPM_TOKEN` repository secret with access to the package. The package workflow uses `publish.yml` when relocated to a standalone repository.
|
package/package.json
CHANGED
|
@@ -1,6 +1,75 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@luckylu.cy/sync-todo-overlay",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"types": "./dist/todo-overlay.d.ts",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": {
|
|
8
|
+
"import": {
|
|
9
|
+
"types": "./dist/todo-overlay.esm.d.ts",
|
|
10
|
+
"default": "./dist/todo-overlay.esm.js"
|
|
11
|
+
},
|
|
12
|
+
"require": {
|
|
13
|
+
"types": "./dist/todo-overlay.d.cts",
|
|
14
|
+
"default": "./dist/todo-overlay.cjs"
|
|
15
|
+
}
|
|
16
|
+
},
|
|
17
|
+
"./vue": {
|
|
18
|
+
"import": {
|
|
19
|
+
"types": "./dist/todo-overlay.vue.esm.d.ts",
|
|
20
|
+
"default": "./dist/todo-overlay.vue.esm.js"
|
|
21
|
+
},
|
|
22
|
+
"require": {
|
|
23
|
+
"types": "./dist/todo-overlay.vue.d.cts",
|
|
24
|
+
"default": "./dist/todo-overlay.vue.cjs"
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
"./style": "./dist/style.css",
|
|
28
|
+
"./cjs": {
|
|
29
|
+
"types": "./dist/todo-overlay.d.cts",
|
|
30
|
+
"default": "./dist/todo-overlay.cjs"
|
|
31
|
+
},
|
|
32
|
+
"./react": {
|
|
33
|
+
"import": {
|
|
34
|
+
"types": "./dist/todo-overlay.react.esm.d.ts",
|
|
35
|
+
"default": "./dist/todo-overlay.react.esm.js"
|
|
36
|
+
},
|
|
37
|
+
"require": {
|
|
38
|
+
"types": "./dist/todo-overlay.react.d.cts",
|
|
39
|
+
"default": "./dist/todo-overlay.react.cjs"
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
},
|
|
43
|
+
"files": [
|
|
44
|
+
"dist/",
|
|
45
|
+
"README.md"
|
|
46
|
+
],
|
|
47
|
+
"peerDependencies": {
|
|
48
|
+
"react": ">=18",
|
|
49
|
+
"vue": "^3.5.0"
|
|
50
|
+
},
|
|
51
|
+
"peerDependenciesMeta": {
|
|
52
|
+
"react": {
|
|
53
|
+
"optional": true
|
|
54
|
+
},
|
|
55
|
+
"vue": {
|
|
56
|
+
"optional": true
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
"scripts": {
|
|
60
|
+
"build": "node build.mjs"
|
|
61
|
+
},
|
|
62
|
+
"devDependencies": {
|
|
63
|
+
"@types/react": "^19.2.0"
|
|
64
|
+
},
|
|
65
|
+
"description": "A Vue, React and vanilla JavaScript quick-add overlay for Sync Todo",
|
|
66
|
+
"repository": {
|
|
67
|
+
"type": "git",
|
|
68
|
+
"url": "git+https://github.com/luckydonald/docker-tg-bot.git",
|
|
69
|
+
"directory": "sync_todo/frontend/embed"
|
|
70
|
+
},
|
|
71
|
+
"publishConfig": {
|
|
72
|
+
"access": "public",
|
|
73
|
+
"registry": "https://registry.npmjs.org"
|
|
74
|
+
}
|
|
75
|
+
}
|