@keepkit/core 0.28.2 → 0.28.4

package/README.md

@@ -30,7 +30,9 @@ const list = useKeepList({
 
 `KeepListQuery`は`targetType`、`tags`、`search`、`sort`、`pagination`、`filter`、`savedBetween`で構成されます。`queryKeepItems`はReactなしで同じ条件を適用できます。
 
-再発見には`useKeepItem(item).recordOpen()`で`lastOpenedAt`を記録し、`activity`の`opened`、`lastOpenedBefore`、`lastOpenedAfter`、`inactiveForMs`で絞り込めます。`createRediscoveryQuery()`は`never-opened`、`forgotten`、`recently-opened`のCore向けプリセットを提供し、`useKeepRediscovery()`はReact向けの一覧hookです。
+整理状態は`organization: { collection, tags, note }`の`assigned` / `unassigned`で絞り込めます。`createInboxQuery()`は未分類アイテム向けの既定queryを返します。`useKeepList()`は一括archive、pin、collection移動を提供します。Saved Viewは`KeepSavedViewStorage` / `LocalStorageKeepSavedViewStorage`でアイテムと分けて保存できます。
+
+再発見には`useKeepItem(item).recordOpen()`で`lastOpenedAt`を記録し、`activity`の`opened`、`lastOpenedBefore`、`lastOpenedAfter`、`inactiveForMs`で絞り込めます。`inactiveForMs`は開封済みなら`lastOpenedAt`、未開封なら`savedAt`を基準に判定します。開封記録だけでは`updatedAt`を変更せず、同期・mergeでは新しいActivityを保持します。`createRediscoveryQuery()`は`never-opened`、`forgotten`、`recently-opened`のCore向けプリセットを提供し、`useKeepRediscovery()`はReact向けの一覧hookです。
 
 保存順を巡回ルートとして管理する場合は、`reorderKeepItems` / `moveKeepItem`、Reactでは`useKeepNavigator`と`useKeepList().reorder()` / `.move()`を利用できます。`getKeepNavigationState`は現在・前・次のアイテムと進行度を返します。
 
@@ -40,7 +42,7 @@ const list = useKeepList({
 
 保存対象の公開状態は`KeepItem.status`（`expired`、`removed`、`private`など）と`statusReason`で保持できます。`KeepProvider`の`validateItem` / `resolveItem`を指定すると、引数なしの`revalidateItems()`で検証できます。`revalidateItems`に`removeStatuses`を渡すと検出したアイテムを保存一覧から削除します。`SyncStorageAdapter`は`userId`、`tenantId`、`maxRetries`、`retryDelayMs`、`retryBackoff`に対応し、`retrySync()`で失敗後の同期を再開できます。
 
-v0.28.2では、利用履歴とRediscovery queryに加えて、UIパッケージのフィルター状態可視化を追加しました。UIパッケージのフローティング巡回UI、保存順プレイリスト、URL状態codec、ユーザー／テナント分離、認証付き同期も引き続き利用できます。
+v0.28.4では、空のコレクションと変更した名前をブラウザー内に永続化し、再読み込み後に復元できるようになりました。Inbox、Saved View、利用履歴、Rediscovery query、URL状態codec、認証付き同期も利用できます。
 
 `createAuthenticatedSyncKit`は、リクエストごとの`getAuthToken`、注入可能なpush/pull transport、401/403時の再認証callback、永続オフラインキュー、`setScope`による安全なユーザー／テナント切替を提供します。詳細は[`examples/authenticated-sync`](../../examples/authenticated-sync/README.md)を参照してください。
 
@@ -77,7 +79,9 @@ const list = useKeepList({
 
 `KeepItemInput` contains `id`, `meta`, `targetType`, `note`, `tags`, and the optional persisted `order`. KeepKit owns persistence timestamps and tag normalization. `KeepListQuery` uses the canonical `targetType`, `tags`, `search`, `sort`, `pagination`, `filter`, and `savedBetween` fields.
 
-For rediscovery, call `useKeepItem(item).recordOpen()` to persist `lastOpenedAt`, then filter with `activity.opened`, `lastOpenedBefore`, `lastOpenedAfter`, or `inactiveForMs`. `createRediscoveryQuery()` provides framework-neutral `never-opened`, `forgotten`, and `recently-opened` presets, while `useKeepRediscovery()` provides the React list hook.
+Filter organization with `organization: { collection, tags, note }`, each set to `assigned` or `unassigned`. `createInboxQuery()` returns the default unassigned query. `useKeepList()` includes batch archive, pin, and collection mutations. Saved Views use `KeepSavedViewStorage` and `LocalStorageKeepSavedViewStorage`, separate from item storage.
+
+For rediscovery, call `useKeepItem(item).recordOpen()` to persist `lastOpenedAt`, then filter with `activity.opened`, `lastOpenedBefore`, `lastOpenedAfter`, or `inactiveForMs`. `inactiveForMs` uses `lastOpenedAt` for opened items and `savedAt` for never-opened items. Recording an open does not change `updatedAt`, and sync/merge preserves newer activity independently. `createRediscoveryQuery()` provides framework-neutral `never-opened`, `forgotten`, and `recently-opened` presets, while `useKeepRediscovery()` provides the React list hook.
 
 Use `reorderKeepItems` / `moveKeepItem` for framework-neutral route ordering, or `useKeepNavigator` with `useKeepList().reorder()` / `.move()` in React. `getKeepNavigationState` returns the current, previous, next, and progress state.
 
@@ -87,7 +91,7 @@ Use `@keepkit/core/core` for framework-neutral code, `@keepkit/core/react` for R
 
 `KeepItem.status` and `statusReason` preserve source availability such as `expired`, `removed`, and `private`. Configure `KeepProvider` with `validateItem` / `resolveItem` to make `revalidateItems()` use those hooks by default. Pass `removeStatuses` to remove detected items from storage. `SyncStorageAdapter` supports scoped queues with `userId` and `tenantId`, configurable retries/backoff, and explicit `retrySync()` recovery.
 
-v0.28.2 adds the filter-state UI on top of activity tracking and Rediscovery queries. The UI package's floating tour UI and Core's persisted playlist ordering, URL state codecs, user/tenant isolation, setup presets, and token-aware authenticated sync remain available.
+v0.28.4 persists empty collections and renamed labels in browser storage so they survive reloads. Inbox, Saved Views, activity tracking, Rediscovery queries, URL state codecs, user/tenant isolation, and authenticated sync are also available.
 
 `createAuthenticatedSyncKit` provides a per-request `getAuthToken`, injectable push/pull transport, 401/403 reauthentication callbacks, persistent offline queues, and `setScope` for safe user or tenant changes. See [`examples/authenticated-sync`](../../examples/authenticated-sync/README.md) for a recipe.
 
@@ -97,6 +101,10 @@ The v0.5 factory returns `Provider`, `Button`, `useContext`, `useItem`, `useList
 
 `KeepItem` and `KeepItemInput` accept optional `archived`, `pinned`, and `collectionId` fields. `useKeepList` defaults to unarchived items; pass `archived: true` for the archive, `archiveScope: "all"` for both scopes, `collectionId` for an exact collection filter, and `pinnedFirst: true` to stably promote pinned items without changing the existing order inside either group. `useKeepCollections({ targetType, orderBy })` derives de-duplicated collection IDs, names, and counts from the complete saved-item snapshot. `useKeepItem` and the provider expose `toggleArchive`, `archiveItem`, `unarchiveItem`, `togglePin`, and `moveToCollection` operations. Each operation updates `updatedAt`, removes an empty collection ID, and uses the normal persistence, rollback, plugin, and `onChange` pipeline.
 
+The standard browser adapters persist explicit collection definitions, including empty collections and renamed labels, separately from items. A custom `StorageAdapter` can opt in by implementing `getCollections`, `setCollection`, and `removeCollection`; without them, collection management remains in memory. `clear()` and JSON backups still affect items only, and collection definitions do not enter remote sync.
+
 ## アーカイブ・ピン留め・コレクション
 
 `KeepItem` と `KeepItemInput` は `archived`、`pinned`、`collectionId` を任意で受け取れます。`useKeepList` は未アーカイブを既定とし、`archived: true` でアーカイブを、`archiveScope: "all"` で両方を、`collectionId` で完全一致のコレクションを取得できます。`useKeepCollections({ targetType, orderBy })` は全保存アイテムからコレクションID・名前・件数を重複なく導出します。`pinnedFirst: true` は既存の順序を保ったままピン留め項目を先頭へ安定移動します。`useKeepItem` と Provider には `toggleArchive`、`archiveItem`、`unarchiveItem`、`togglePin`、`moveToCollection` を追加しました。各操作は `updatedAt` を更新し、空のコレクション ID はプロパティを削除して、既存の永続化・rollback・plugin・`onChange` 経路を利用します。
+
+標準ブラウザーストレージは、空のコレクションと変更した名前をアイテムとは別に永続化します。独自の`StorageAdapter`では`getCollections`、`setCollection`、`removeCollection`を実装すると永続化でき、未実装時は従来どおり画面内の状態として扱います。`clear()`とJSONバックアップは引き続きアイテムのみを対象とし、コレクション定義はリモート同期に含まれません。

package/dist/{chunk-HDML3IDX.js → chunk-2TENUU7B.js}

@@ -64,7 +64,13 @@ function mergeKeepItemLists(remoteItems, localItems) {
   const byId = new Map(remoteItems.map((item) => [item.id, item]));
   for (const localItem of localItems) {
     const remoteItem = byId.get(localItem.id);
-    if (!remoteItem || localItem.updatedAt > remoteItem.updatedAt) byId.set(localItem.id, localItem);
+    if (!remoteItem) {
+      byId.set(localItem.id, localItem);
+      continue;
+    }
+    const content = localItem.updatedAt > remoteItem.updatedAt ? localItem : remoteItem;
+    const lastOpenedAt = remoteItem.lastOpenedAt === void 0 ? localItem.lastOpenedAt : localItem.lastOpenedAt === void 0 ? remoteItem.lastOpenedAt : Math.max(remoteItem.lastOpenedAt, localItem.lastOpenedAt);
+    byId.set(localItem.id, lastOpenedAt === void 0 ? content : { ...content, lastOpenedAt });
   }
   return [...byId.values()].sort((a, b) => b.updatedAt - a.updatedAt);
 }
@@ -75,6 +81,9 @@ function isKeepItem(value) {
 function isKeepItemArray(value) {
   return Array.isArray(value) && value.every(isKeepItem);
 }
+function isKeepCollectionDefinition(value) {
+  return isRecord(value) && typeof value.id === "string" && value.id.trim().length > 0 && typeof value.name === "string" && value.name.trim().length > 0 && (value.scope === void 0 || isSyncScope(value.scope));
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -96,6 +105,17 @@ var ScopedStorageAdapter = class {
     this.scope = scope;
     const scopeKey = getKeepScopeKey(scope);
     this.storageKey = base.storageKey ? base.storageKey.endsWith(scopeKey) && scopeKey ? base.storageKey : `${base.storageKey}${scopeKey}` : void 0;
+    if (base.getCollections && base.setCollection && base.removeCollection) {
+      const getCollections = base.getCollections.bind(base);
+      const setCollection = base.setCollection.bind(base);
+      const removeCollection = base.removeCollection.bind(base);
+      this.getCollections = async () => {
+        const collections = await getCollections();
+        return this.scope ? collections.filter((collection) => isSameKeepScope(collection.scope, this.scope)) : collections;
+      };
+      this.setCollection = (collection) => setCollection({ ...collection, ...this.scope ? { scope: this.scope } : {} });
+      this.removeCollection = (id) => removeCollection(id, this.scope);
+    }
   }
   async getAll() {
     const items = await this.base.getAll();
@@ -356,6 +376,18 @@ var SyncStorageAdapter = class {
     this.retryDelayMs = Math.max(0, options.retryDelayMs ?? 0);
     this.retryBackoff = Math.max(1, options.retryBackoff ?? 2);
     this.storageKey = this.local.storageKey;
+    if (this.local.getCollections && this.local.setCollection && this.local.removeCollection) {
+      const getCollections = this.local.getCollections.bind(this.local);
+      const setCollection = this.local.setCollection.bind(this.local);
+      const removeCollection = this.local.removeCollection.bind(this.local);
+      this.getCollections = async () => {
+        const collections = await getCollections();
+        const scope = this.scope;
+        return scope ? collections.filter((collection) => sameScope(collection.scope, scope)) : collections;
+      };
+      this.setCollection = (collection) => setCollection({ ...collection, ...this.scope ? { scope: this.scope } : {} });
+      this.removeCollection = (id) => removeCollection(id, this.scope);
+    }
     if (typeof window !== "undefined") {
       this.onlineHandler = () => void this.flushSync();
       window.addEventListener("online", this.onlineHandler);
@@ -644,11 +676,21 @@ var SyncStorageAdapter = class {
       const pendingIds = new Set(this.queueItems.map((operation) => operation.id));
       const localItems = await this.getAll();
       const localById = new Map(localItems.map((item) => [item.id, item]));
-      const incoming = remoteItems.filter((item) => {
-        if (this.scope && item.scope && !sameScope(item.scope, this.scope)) return false;
+      const remoteById = /* @__PURE__ */ new Map();
+      for (const item of remoteItems) {
+        if (this.scope && item.scope && !sameScope(item.scope, this.scope)) continue;
+        if (pendingIds.has(item.id)) continue;
+        const previous = remoteById.get(item.id);
+        remoteById.set(item.id, previous ? mergeKeepItemLists([item], [previous])[0] ?? item : item);
+      }
+      const incoming = [...remoteById.values()].flatMap((item) => {
         const current = localById.get(item.id);
-        return !pendingIds.has(item.id) && (!current || item.updatedAt >= current.updatedAt);
-      }).map((item) => this.applyScope(item));
+        if (current && item.updatedAt < current.updatedAt && (item.lastOpenedAt ?? 0) <= (current.lastOpenedAt ?? 0)) {
+          return [];
+        }
+        const merged = current ? mergeKeepItemLists([item], [current])[0] ?? item : item;
+        return [this.applyScope(merged)];
+      });
       if (incoming.length === 0) return true;
       await persistKeepItems(this.local, incoming);
       this.notifyDataListeners();
@@ -755,6 +797,29 @@ var FallbackStorageAdapter = class {
     this.migrateFallbackOnEmpty = options.migrateFallbackOnEmpty ?? false;
     this.mirrorWrites = options.mirrorWrites ?? false;
     this.storageKey = options.fallback.storageKey ?? options.primary.storageKey;
+    if (this.primary.getCollections && this.primary.setCollection && this.primary.removeCollection && this.fallback.getCollections && this.fallback.setCollection && this.fallback.removeCollection) {
+      const fallbackGetCollections = this.fallback.getCollections.bind(this.fallback);
+      this.getCollections = async () => {
+        const collections = await this.execute((adapter) => {
+          if (!adapter.getCollections) throw new Error("Collection storage is unavailable.");
+          return adapter.getCollections();
+        });
+        if (this.active === "primary" && this.migrateFallbackOnEmpty && collections.length === 0) {
+          const fallbackCollections = await fallbackGetCollections();
+          for (const collection of fallbackCollections) await this.setCollection?.(collection);
+          return fallbackCollections;
+        }
+        return collections;
+      };
+      this.setCollection = (collection) => this.executeWrite((adapter) => {
+        if (!adapter.setCollection) throw new Error("Collection storage is unavailable.");
+        return adapter.setCollection(collection);
+      });
+      this.removeCollection = (id, scope) => this.executeWrite((adapter) => {
+        if (!adapter.removeCollection) throw new Error("Collection storage is unavailable.");
+        return adapter.removeCollection(id, scope);
+      });
+    }
   }
   get isUsingFallback() {
     return this.active === "fallback";
@@ -879,8 +944,16 @@ function createStorageAdapter(options) {
   const subscribe = options.subscribe;
   const setMany = options.setMany;
   const removeMany = options.removeMany;
+  const getCollections = options.getCollections;
+  const setCollection = options.setCollection;
+  const removeCollection = options.removeCollection;
   return {
     getAll: async () => options.getAll(),
+    ...getCollections && setCollection && removeCollection ? {
+      getCollections: async () => getCollections(),
+      setCollection: async (collection) => setCollection(collection),
+      removeCollection: async (id, scope) => removeCollection(id, scope)
+    } : {},
     set: async (item) => options.set(item),
     ...setMany ? { setMany: async (items) => setMany(items) } : {},
     remove: async (id) => options.remove(id),
@@ -929,6 +1002,45 @@ var LocalStorageAdapter = class {
       });
     }
   }
+  async getCollections() {
+    if (!this.storage) return [];
+    const storageKey = `${this.storageKey}:collections`;
+    let raw;
+    try {
+      raw = this.storage.getItem(storageKey);
+    } catch (cause) {
+      throw new KeepStorageAccessError({ operation: "getAll", storageKey, cause });
+    }
+    if (!raw) return [];
+    try {
+      const value = JSON.parse(raw);
+      if (!Array.isArray(value) || !value.every(isKeepCollectionDefinition)) {
+        throw new KeepStorageParseError({ operation: "getAll", storageKey });
+      }
+      return value;
+    } catch (cause) {
+      if (cause instanceof KeepStorageParseError) throw cause;
+      throw new KeepStorageParseError({ operation: "getAll", storageKey, cause });
+    }
+  }
+  async setCollection(collection) {
+    if (!isKeepCollectionDefinition(collection)) throw new Error("Collection id and name are required.");
+    const current = await this.getCollections();
+    await this.writeCollections(
+      [
+        ...current.filter((entry) => entry.id !== collection.id || !isSameKeepScope(entry.scope, collection.scope)),
+        collection
+      ],
+      "set"
+    );
+  }
+  async removeCollection(id, scope) {
+    const current = await this.getCollections();
+    await this.writeCollections(
+      current.filter((entry) => entry.id !== id || !isSameKeepScope(entry.scope, scope)),
+      "remove"
+    );
+  }
   async set(item) {
     await this.setMany([item]);
   }
@@ -969,7 +1081,7 @@ var LocalStorageAdapter = class {
   subscribe(listener) {
     if (typeof window === "undefined") return () => void 0;
     const handleStorage = (event) => {
-      if (event.key !== null && event.key !== this.storageKey) return;
+      if (event.key !== null && event.key !== this.storageKey && event.key !== `${this.storageKey}:collections`) return;
       listener();
     };
     window.addEventListener("storage", handleStorage);
@@ -994,6 +1106,16 @@ var LocalStorageAdapter = class {
       });
     }
   }
+  async writeCollections(collections, operation) {
+    if (!this.storage) return;
+    const storageKey = `${this.storageKey}:collections`;
+    try {
+      this.storage.setItem(storageKey, JSON.stringify(collections));
+    } catch (cause) {
+      if (isQuotaExceededError(cause)) throw new KeepStorageQuotaError({ operation, storageKey, cause });
+      throw new KeepStorageAccessError({ operation, storageKey, cause });
+    }
+  }
 };
 var IndexedDBAdapter = class {
   constructor(options = {}) {
@@ -1018,6 +1140,32 @@ var IndexedDBAdapter = class {
       throw new KeepStorageAccessError({ operation: "getAll", storageKey: this.storageKey, cause });
     }
   }
+  async getCollections() {
+    const database = await this.openCollections("getAll");
+    if (!database) return [];
+    const storageKey = `${this.storageKey}:collections`;
+    try {
+      const transaction = database.transaction("collections", "readonly");
+      const value = await requestToPromise2(transaction.objectStore("collections").getAll());
+      if (!Array.isArray(value) || !value.every((entry) => isRecord(entry) && typeof entry.key === "string" && isKeepCollectionDefinition(entry))) {
+        throw new KeepStorageParseError({ operation: "getAll", storageKey });
+      }
+      return value.map(({ key: _key, ...collection }) => collection);
+    } catch (cause) {
+      if (cause instanceof KeepStorageParseError) throw cause;
+      throw new KeepStorageAccessError({ operation: "getAll", storageKey, cause });
+    }
+  }
+  async setCollection(collection) {
+    if (!isKeepCollectionDefinition(collection)) throw new Error("Collection id and name are required.");
+    await this.writeCollection(
+      "set",
+      (store) => store.put({ ...collection, key: collectionKey(collection.id, collection.scope) })
+    );
+  }
+  async removeCollection(id, scope) {
+    await this.writeCollection("remove", (store) => store.delete(collectionKey(id, scope)));
+  }
   async set(item) {
     return this.setMany([item]);
   }
@@ -1087,6 +1235,47 @@ var IndexedDBAdapter = class {
     channel.postMessage({ type: "keepkit:changed" });
     channel.close();
   }
+  async writeCollection(operation, write) {
+    const database = await this.openCollections(operation);
+    if (!database) return;
+    const storageKey = `${this.storageKey}:collections`;
+    try {
+      const transaction = database.transaction("collections", "readwrite");
+      write(transaction.objectStore("collections"));
+      await transactionToPromise2(transaction);
+      this.notifySubscribers();
+    } catch (cause) {
+      if (isQuotaExceededError(cause)) throw new KeepStorageQuotaError({ operation, storageKey, cause });
+      throw new KeepStorageAccessError({ operation, storageKey, cause });
+    }
+  }
+  openCollections(operation) {
+    if (!this.indexedDB) return Promise.resolve(void 0);
+    const storageKey = `${this.storageKey}:collections`;
+    if (!this.collectionDatabasePromise) {
+      this.collectionDatabasePromise = new Promise((resolve, reject) => {
+        let request;
+        try {
+          request = this.indexedDB?.open(storageKey, 1);
+        } catch (cause) {
+          reject(cause);
+          return;
+        }
+        request.onupgradeneeded = () => {
+          if (!request.result.objectStoreNames.contains("collections")) {
+            request.result.createObjectStore("collections", { keyPath: "key" });
+          }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+        request.onblocked = () => reject(request.error ?? new Error("IndexedDB collection storage open was blocked."));
+      });
+    }
+    return this.collectionDatabasePromise.catch((cause) => {
+      this.collectionDatabasePromise = void 0;
+      throw new KeepStorageAccessError({ operation, storageKey, cause });
+    });
+  }
   open(operation) {
     if (!this.indexedDB) return Promise.resolve(void 0);
     if (!this.databasePromise) {
@@ -1115,6 +1304,9 @@ var IndexedDBAdapter = class {
     });
   }
 };
+function collectionKey(id, scope) {
+  return JSON.stringify([scope?.tenantId ?? null, scope?.userId ?? null, id]);
+}
 function getBrowserStorage2() {
   if (typeof window === "undefined") return void 0;
   try {
@@ -1182,4 +1374,4 @@ export {
   LocalStorageAdapter,
   IndexedDBAdapter
 };
-//# sourceMappingURL=chunk-HDML3IDX.js.map
+//# sourceMappingURL=chunk-2TENUU7B.js.map