@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.
Files changed (2) hide show
  1. package/README.md +240 -2
  2. package/package.json +73 -4
package/README.md CHANGED
@@ -1,3 +1,241 @@
1
- # Temporary Holding Version
1
+ # Sync Todo overlay
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ }