@wcstack/eyedropper 1.19.1 → 1.21.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.ja.md +5 -0
- package/README.md +6 -0
- package/dist/index.d.ts +112 -26
- package/dist/index.esm.js +516 -94
- package/dist/index.esm.js.map +1 -1
- package/dist/index.esm.min.js +1 -1
- package/dist/index.esm.min.js.map +1 -1
- package/package.json +1 -1
package/README.ja.md
CHANGED
|
@@ -118,9 +118,14 @@ npm install @wcstack/eyedropper
|
|
|
118
118
|
| `loading` | `wcs-eyedropper:loading-changed` | スポイトカーソルが有効な間(`open()` 呼び出しが進行中)は `true`。 |
|
|
119
119
|
| `error` | `wcs-eyedropper:error` | 真のプラットフォーム障害(ピッカーがキャンセルされた場合を除く全て)。まだ失敗が無い場合、または次の `open()` 呼び出しでリセットされた後は `null`。 |
|
|
120
120
|
| `cancelled` | `wcs-eyedropper:cancelled-changed` | 選択が完了しなかった場合に `true` — ユーザーが Escape を押した場合と、呼び出し元が `abort()` を呼んだ場合の両方。どちらも同じ `AbortError` として現れ、区別されない。 |
|
|
121
|
+
| `errorInfo` | `wcs-eyedropper:error-info-changed` | serializable な失敗 taxonomy(安定 `code` / `phase` / `recoverable`)、または `null`。追加的で `error` の shape は不変。`code` は unsupported なら `capability-missing`、真の失敗なら `pick-failed`。キャンセルは `cancelled` であり `errorInfo` ではない。 |
|
|
121
122
|
|
|
122
123
|
`cancelled` と `error` はどちらも、次の `open()` 呼び出しの **開始時** にリセットされる(`false` / `null`)ため、前回の呼び出しの古い結果が次回の結果に残り続けることはありません。
|
|
123
124
|
|
|
125
|
+
**並行制御。** `EyeDropper.open()` は `AbortSignal` を受けるため、`<wcs-eyedropper>` は共有
|
|
126
|
+
io-core lane を `latest` policy で用いる(`<wcs-fetch>` と同様): 新しい `open()` が進行中の
|
|
127
|
+
呼び出しを **supersede**(abort)し、`abort()` コマンドは実行中の選択をキャンセルする。
|
|
128
|
+
|
|
124
129
|
## コマンド
|
|
125
130
|
|
|
126
131
|
| コマンド | 非同期 | 説明 |
|
package/README.md
CHANGED
|
@@ -118,9 +118,15 @@ npm install @wcstack/eyedropper
|
|
|
118
118
|
| `loading` | `wcs-eyedropper:loading-changed` | `true` while the eyedropper cursor is active (an `open()` call is in flight). |
|
|
119
119
|
| `error` | `wcs-eyedropper:error` | A true platform failure (anything other than the picker being dismissed). `null` when there has been no failure yet, or after the next `open()` call resets it. |
|
|
120
120
|
| `cancelled` | `wcs-eyedropper:cancelled-changed` | `true` when the pick did not complete — either the user pressed Escape, or the caller invoked `abort()`. Both surface as the same `AbortError` and are not distinguished. |
|
|
121
|
+
| `errorInfo` | `wcs-eyedropper:error-info-changed` | Serializable failure taxonomy (stable `code` / `phase` / `recoverable`), or `null`. Additive — the `error` shape is unchanged; `code` is `capability-missing` when unsupported or `pick-failed` on a genuine failure. Cancellation is `cancelled`, not `errorInfo`. |
|
|
121
122
|
|
|
122
123
|
`cancelled` and `error` are both reset (`false` / `null`) at the **start** of the next `open()` call, so a stale outcome from a previous call never lingers into the next one's result.
|
|
123
124
|
|
|
125
|
+
**Concurrency.** `EyeDropper.open()` accepts an `AbortSignal`, so `<wcs-eyedropper>`
|
|
126
|
+
runs its calls through the shared io-core lane with the `latest` policy (like
|
|
127
|
+
`<wcs-fetch>`): a new `open()` **supersedes** the in-flight one (aborting it), and
|
|
128
|
+
the `abort()` command cancels the active pick.
|
|
129
|
+
|
|
124
130
|
## Commands
|
|
125
131
|
|
|
126
132
|
| Command | Async | Description |
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* platform-capability.ts
|
|
3
|
+
*
|
|
4
|
+
* Phase 6(docs/architecture-hardening/09-remediation-design.md §7.2 /
|
|
5
|
+
* 07-browser-capability-variance.md)の browser capability 判定と error taxonomy の
|
|
6
|
+
* 汎用プリミティブ。node 固有の capability registry / error code は各パッケージが
|
|
7
|
+
* 別ファイルで宣言し、この汎用層(型 + assess 機構)を import する。
|
|
8
|
+
*
|
|
9
|
+
* 原則:
|
|
10
|
+
* - feature detection は境界(利用直前)で行う。module 評価時に browser global を
|
|
11
|
+
* 参照しない(SSR / worker で import が失敗しない)。
|
|
12
|
+
* - capability ID(`web.fetch` 等)は文字列を global property path として eval せず、
|
|
13
|
+
* registry が ID ごとに副作用のない presence probe を対応付ける。
|
|
14
|
+
* - availability / permission / readiness / activity / operation error を 1 つの
|
|
15
|
+
* `ready / unsupported / error` enum に畳まない。required 欠如は開始しない、
|
|
16
|
+
* optional 欠如は宣言済み fallback で readiness を `degraded` にする。
|
|
17
|
+
*
|
|
18
|
+
* 配置: 本ファイルは /io-core/ の単一正典であり、scripts/sync-io-core.mjs が
|
|
19
|
+
* 各 IO ノードの src/core/ へ生成コピー (AUTO-GENERATED, 編集禁止) を配布する。
|
|
20
|
+
* `protocol/wcBindable.ts` と同じ copy-distribution 方式で、ランタイム依存を導入せず
|
|
21
|
+
* 各パッケージのバンドルへ inline される (zero-runtime-dep / 自己完結 CDN を維持)。
|
|
22
|
+
* 編集はこの正典に対して行い、`node scripts/sync-io-core.mjs` で再配布する。
|
|
23
|
+
*
|
|
24
|
+
* pure(module 評価時に browser global 非参照)。
|
|
25
|
+
*/
|
|
26
|
+
type Availability = "available" | "missing" | "unknown";
|
|
27
|
+
type PermissionState = "granted" | "denied" | "prompt" | "not-applicable" | "unknown";
|
|
28
|
+
type Readiness = "idle" | "ready" | "degraded";
|
|
29
|
+
type Activity = "inactive" | "active";
|
|
30
|
+
type PreconditionState = "satisfied" | "required" | "not-applicable";
|
|
31
|
+
/** operation error の phase(taxonomy)。 */
|
|
32
|
+
type WcsIoErrorPhase = "probe" | "start" | "execute" | "decode" | "commit" | "dispose";
|
|
33
|
+
/** serializable な error info(non-cloneable な cause とは分離。DevTools / remote へは info のみ)。 */
|
|
34
|
+
interface WcsIoErrorInfo {
|
|
35
|
+
readonly code: string;
|
|
36
|
+
readonly phase: WcsIoErrorPhase;
|
|
37
|
+
readonly recoverable: boolean;
|
|
38
|
+
readonly capabilityId?: string;
|
|
39
|
+
readonly message: string;
|
|
40
|
+
}
|
|
41
|
+
interface PlatformAssessment {
|
|
42
|
+
readonly availability: ReadonlyMap<string, Availability>;
|
|
43
|
+
readonly permission: PermissionState;
|
|
44
|
+
readonly readiness: Readiness;
|
|
45
|
+
readonly activity: Activity;
|
|
46
|
+
readonly preconditions: {
|
|
47
|
+
readonly secureContext: PreconditionState;
|
|
48
|
+
readonly userActivation: PreconditionState;
|
|
49
|
+
};
|
|
50
|
+
readonly epoch: number;
|
|
51
|
+
readonly lastError?: WcsIoErrorInfo;
|
|
52
|
+
}
|
|
53
|
+
|
|
1
54
|
interface IWcBindableProperty {
|
|
2
55
|
readonly name: string;
|
|
3
56
|
readonly event: string;
|
|
@@ -13,7 +66,8 @@ interface IWcBindableCommand {
|
|
|
13
66
|
}
|
|
14
67
|
interface IWcBindable {
|
|
15
68
|
readonly protocol: "wc-bindable";
|
|
16
|
-
|
|
69
|
+
/** Integer protocol version. All versions >= 1 are core-compatible. */
|
|
70
|
+
readonly version: number;
|
|
17
71
|
readonly properties: readonly IWcBindableProperty[];
|
|
18
72
|
readonly inputs?: readonly IWcBindableInput[];
|
|
19
73
|
readonly commands?: readonly IWcBindableCommand[];
|
|
@@ -55,6 +109,7 @@ interface WcsEyedropperCoreValues {
|
|
|
55
109
|
loading: boolean;
|
|
56
110
|
error: any;
|
|
57
111
|
cancelled: boolean;
|
|
112
|
+
errorInfo: WcsIoErrorInfo | null;
|
|
58
113
|
}
|
|
59
114
|
/**
|
|
60
115
|
* Value types for the Shell (`<wcs-eyedropper>`) — identical observable
|
|
@@ -71,34 +126,29 @@ declare function getConfig(): IConfig;
|
|
|
71
126
|
* Headless EyeDropper primitive. A thin, framework-agnostic wrapper around
|
|
72
127
|
* `new EyeDropper().open(options)` exposed through the wc-bindable protocol.
|
|
73
128
|
*
|
|
74
|
-
*
|
|
75
|
-
* (
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
* option, so — unlike Web Share — a caller has a real platform mechanism to
|
|
83
|
-
* cancel an in-flight color pick. The shape mirrors `FetchCore.abort()`
|
|
84
|
-
* (packages/fetch/src/core/FetchCore.ts:159-164) including the identity check
|
|
85
|
-
* on the locally-held `AbortController` in the `finally` block
|
|
86
|
-
* (packages/fetch/src/core/FetchCore.ts:312-314), so a fast abort()→open()
|
|
87
|
-
* sequence never lets a stale controller null out the new call's controller.
|
|
129
|
+
* Concurrency is owned by the shared `OperationLane` (io-core) with the `latest`
|
|
130
|
+
* policy: `EyeDropper.open()` accepts a `{signal}`, so — unlike Web Share / Contact
|
|
131
|
+
* Picker (exhaust) — a caller has a real platform mechanism to cancel an in-flight
|
|
132
|
+
* pick. A new `open()` supersedes the previous one (the lane aborts its
|
|
133
|
+
* AbortController and the superseded completion fails the terminal CAS), and the
|
|
134
|
+
* `abort()` command aborts the active pick. This replaces the ad-hoc `_gen` +
|
|
135
|
+
* `_abortController` + finally-block identity check with the same lane FetchCore
|
|
136
|
+
* uses; the lane owns the per-attempt AbortController and the commit guard.
|
|
88
137
|
*
|
|
89
138
|
* Both the user dismissing the picker with Escape and the caller invoking
|
|
90
|
-
* `abort()` reject `open()` with the same `AbortError` — both land on
|
|
91
|
-
*
|
|
139
|
+
* `abort()` reject `open()` with the same `AbortError` — both land on `cancelled`
|
|
140
|
+
* without distinction (docs/eyedropper-tag-design.md §2).
|
|
92
141
|
*/
|
|
93
142
|
declare class EyedropperCore extends EventTarget {
|
|
94
143
|
static wcBindable: IWcBindable;
|
|
144
|
+
private static readonly REQUIRED_CAPABILITIES;
|
|
95
145
|
private _target;
|
|
96
146
|
private _value;
|
|
97
147
|
private _loading;
|
|
98
148
|
private _error;
|
|
99
149
|
private _cancelled;
|
|
100
|
-
private
|
|
101
|
-
private
|
|
150
|
+
private _errorInfo;
|
|
151
|
+
private _lane;
|
|
102
152
|
private _ready;
|
|
103
153
|
constructor(target?: EventTarget);
|
|
104
154
|
get ready(): Promise<void>;
|
|
@@ -106,18 +156,39 @@ declare class EyedropperCore extends EventTarget {
|
|
|
106
156
|
get loading(): boolean;
|
|
107
157
|
get error(): any;
|
|
108
158
|
get cancelled(): boolean;
|
|
159
|
+
/**
|
|
160
|
+
* The last failure's serializable `WcsIoErrorInfo` (stable `code` / `phase` /
|
|
161
|
+
* `recoverable` / `capabilityId`), or null. Exposed as an additive wc-bindable
|
|
162
|
+
* property (event `wcs-eyedropper:error-info-changed`); the existing `error`
|
|
163
|
+
* property/event are unchanged. Note user/abort cancellation is `cancelled`, not
|
|
164
|
+
* `errorInfo`.
|
|
165
|
+
*/
|
|
166
|
+
get errorInfo(): WcsIoErrorInfo | null;
|
|
167
|
+
/**
|
|
168
|
+
* Whether the required platform capability (`web.eyedropper`) is available right
|
|
169
|
+
* now — decided by call-time feature detection, not User-Agent. Core-only,
|
|
170
|
+
* additive.
|
|
171
|
+
*/
|
|
172
|
+
get supported(): boolean;
|
|
173
|
+
/**
|
|
174
|
+
* Full platform assessment (availability / readiness / preconditions), probed at
|
|
175
|
+
* call time. Core-only opt-in dev / sidecar view.
|
|
176
|
+
*/
|
|
177
|
+
get platformAssessment(): PlatformAssessment;
|
|
109
178
|
observe(): Promise<void>;
|
|
110
179
|
dispose(): void;
|
|
180
|
+
private _commitStep;
|
|
111
181
|
private _setLoading;
|
|
112
182
|
private _setValue;
|
|
113
183
|
private _setError;
|
|
114
184
|
private _setCancelled;
|
|
115
|
-
private
|
|
185
|
+
private _setErrorInfo;
|
|
186
|
+
private _commitErrorInfo;
|
|
116
187
|
/**
|
|
117
|
-
* Cancels an in-flight `open()` call, if any
|
|
118
|
-
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
188
|
+
* Cancels an in-flight `open()` call, if any (a no-op otherwise). Aborts the
|
|
189
|
+
* lane's active AbortController — the in-flight open() then rejects with
|
|
190
|
+
* `AbortError` and lands on `cancelled`. The epoch is not advanced, so the
|
|
191
|
+
* aborted operation keeps eligibility to claim the `aborted` terminal.
|
|
121
192
|
*/
|
|
122
193
|
abort(): void;
|
|
123
194
|
open(): Promise<WcsEyedropperData | null>;
|
|
@@ -145,6 +216,7 @@ declare class WcsEyedropper extends HTMLElement {
|
|
|
145
216
|
get loading(): boolean;
|
|
146
217
|
get error(): any;
|
|
147
218
|
get cancelled(): boolean;
|
|
219
|
+
get errorInfo(): WcsIoErrorInfo | null;
|
|
148
220
|
get connectedCallbackPromise(): Promise<void>;
|
|
149
221
|
open(): Promise<WcsEyedropperData | null>;
|
|
150
222
|
abort(): void;
|
|
@@ -152,5 +224,19 @@ declare class WcsEyedropper extends HTMLElement {
|
|
|
152
224
|
disconnectedCallback(): void;
|
|
153
225
|
}
|
|
154
226
|
|
|
155
|
-
|
|
156
|
-
|
|
227
|
+
/**
|
|
228
|
+
* eyedropperCapabilities.ts
|
|
229
|
+
*
|
|
230
|
+
* EyeDropper node 固有の capability registry と error code。汎用の assess 機構・型は
|
|
231
|
+
* `./platformCapability.js`(/io-core/ から copy-distribution される生成ファイル)から
|
|
232
|
+
* import する。node 固有の宣言はこのハンドライトファイルに置き、生成コピーとは分離する。
|
|
233
|
+
*/
|
|
234
|
+
|
|
235
|
+
/** 安定した eyedropper error code(taxonomy)。値は公開キーとして固定。 */
|
|
236
|
+
declare const WCS_EYEDROPPER_ERROR_CODE: {
|
|
237
|
+
readonly CapabilityMissing: "capability-missing";
|
|
238
|
+
readonly PickFailed: "pick-failed";
|
|
239
|
+
};
|
|
240
|
+
|
|
241
|
+
export { EyedropperCore, WCS_EYEDROPPER_ERROR_CODE, WcsEyedropper, bootstrapEyedropper, getConfig };
|
|
242
|
+
export type { IWritableConfig, IWritableTagNames, WcsEyedropperCoreValues, WcsEyedropperData, WcsEyedropperValues, WcsIoErrorInfo, WcsIoErrorPhase };
|