@urbicon-ui/blocks 6.40.4 → 6.43.2

package/dist/utils/persistent-state.svelte.js

@@ -30,33 +30,88 @@ function debounce(func, wait) {
 /**
  * Create a persistent state that automatically syncs with storage
  * Uses Svelte 5 $state() for reactivity
+ *
+ * Besides `value`, the returned object exposes `hasStoredValue` — whether an
+ * entry for this key exists in storage. That is what lets a consumer tell a
+ * *stored empty* value (`[]`, `''`, `null` — the user cleared it) from *nothing
+ * stored at all*, so a cleared state can win over a default/seed instead of
+ * being re-applied on every load. Two rules keep that signal meaningful: a save
+ * that would not change the stored bytes is skipped, and an instance nobody
+ * wrote to never creates an entry for its own default (so `reset()` is not
+ * undone by the auto-save, and untouched state stays out of storage). Writing
+ * the default *back* — clearing — is a real write and does create the entry.
+ *
+ * Values must round-trip through the configured `serialize`/`deserialize`;
+ * `Set`/`Map` do not under the `JSON.stringify` default (they serialize to
+ * `{}`), so pass converting functions or store plain arrays/objects.
  */
 export function createPersistentState(config) {
     const { key, defaultValue, storage: storageType = 'localStorage', serialize = JSON.stringify, deserialize = JSON.parse, debounceMs = 300, version = 1 } = config;
     const storageKey = `urbicon_${key}_v${version}`;
     const storage = getStorage(storageType);
     // Initialize state with stored value or default
-    const initialValue = loadFromStorage();
-    const state = $state({ value: initialValue });
+    const initial = loadFromStorage();
+    const state = $state({ value: initial.value, hasStored: initial.stored });
+    // A faithful mirror of what storage holds: the exact stored string, or `null`
+    // when the key is absent (or unparseable). It must never claim the default is
+    // stored when it is not — that would make the absent → stored-empty
+    // transition unwritable, which is exactly the state this module exists to
+    // preserve (the user cleared the axis).
+    let lastWritten = initial.raw;
+    // Whether the consumer ever wrote through this instance. Only used to keep an
+    // *untouched* instance from creating an entry for its own default.
+    let touched = false;
+    const defaultSerialized = trySerialize(defaultValue);
+    function trySerialize(value) {
+        try {
+            return serialize(value);
+        }
+        catch {
+            return null;
+        }
+    }
     function loadFromStorage() {
         if (!storage)
-            return defaultValue;
+            return { value: defaultValue, stored: false, raw: null };
         try {
             const stored = storage.getItem(storageKey);
             if (stored === null)
-                return defaultValue;
-            return deserialize(stored);
+                return { value: defaultValue, stored: false, raw: null };
+            return { value: deserialize(stored), stored: true, raw: stored };
         }
         catch (error) {
             console.warn(`Failed to load persistent state for key "${key}":`, error);
-            return defaultValue;
+            // A corrupt entry counts as *absent*, never as "stored": consumers use
+            // `hasStoredValue` to let a stored value win over their own default or
+            // seed, and unparseable junk must not win — it would block that default
+            // forever. The junk itself is left in place until something is actually
+            // written (the first real write overwrites it); an untouched instance
+            // does not clean it up, and does not need to — it reads as absent.
+            return { value: defaultValue, stored: false, raw: null };
         }
     }
     function saveToStorage(value) {
         if (!storage)
             return;
         try {
-            storage.setItem(storageKey, serialize(value));
+            const next = serialize(value);
+            // Storage already holds exactly this — nothing to do.
+            if (next === lastWritten)
+                return;
+            // Never *create* an entry for a value nobody touched. Without this the
+            // auto-save effect below would write every key with its own default on
+            // mount, making `hasStoredValue` useless (an untouched default would be
+            // indistinguishable from a deliberately cleared one) and re-creating the
+            // entry `reset()` just removed. Once the consumer has written — including
+            // writing the default back, i.e. clearing — the write goes through, even
+            // if the key does not exist yet. `forceSave()` obeys the same rule on
+            // purpose: a blanket flush (the table exposes one) must not create an
+            // entry for every untouched axis, which would retire all their seeds.
+            if (!touched && lastWritten === null && next === defaultSerialized)
+                return;
+            storage.setItem(storageKey, next);
+            lastWritten = next;
+            state.hasStored = true;
         }
         catch (error) {
             console.warn(`Failed to save persistent state for key "${key}":`, error);
@@ -73,17 +128,44 @@ export function createPersistentState(config) {
             return state.value;
         },
         set value(newValue) {
+            // Mark the instance as written-to *before* the state change, so the
+            // auto-save effect it triggers knows this is a deliberate value — that is
+            // what lets clearing back to the default create an entry.
+            touched = true;
             state.value = newValue;
         },
+        /**
+         * Whether storage currently holds an entry for this key: `true` when
+         * construction (or `reload()`) found a parseable entry, and after a write
+         * actually reached storage; `false` when the key was absent or corrupt,
+         * after `reset()`, and always without a working storage (SSR, private
+         * mode). Use it to distinguish a stored empty value from an absent one.
+         */
+        get hasStoredValue() {
+            return state.hasStored;
+        },
         /**
          * Reset to default value and clear storage
          */
         reset() {
             state.value = defaultValue;
-            storage?.removeItem(storageKey);
+            try {
+                storage?.removeItem(storageKey);
+            }
+            catch (error) {
+                console.warn(`Failed to clear persistent state for key "${key}":`, error);
+            }
+            state.hasStored = false;
+            // Back to "nothing stored", and untouched again — so the auto-save
+            // triggered by the assignment above does not immediately re-create the
+            // key we just removed. A later write (including clearing) still lands.
+            lastWritten = null;
+            touched = false;
         },
         /**
-         * Force immediate save (bypasses debounce)
+         * Force immediate save (bypasses debounce). A no-op when storage already
+         * holds exactly this value, and — like the auto-save — when the instance
+         * was never written to and still holds its default.
          */
         forceSave() {
             saveToStorage(state.value);
@@ -92,7 +174,13 @@ export function createPersistentState(config) {
          * Reload from storage
          */
         reload() {
-            state.value = loadFromStorage();
+            const next = loadFromStorage();
+            state.value = next.value;
+            state.hasStored = next.stored;
+            lastWritten = next.raw;
+            // The value now mirrors storage again; nothing here came from the
+            // consumer, so an absent key stays absent until the next real write.
+            touched = false;
         }
     };
 }

package/docs/MIGRATION-v5.md

@@ -80,6 +80,35 @@ The dead `tableVariants` export is removed (was unused in any consumer).
 <Table data={rows} columns={cols} />
 ```
 
+## 3b. Table state snippets renamed (v6.41)
+
+The Table's three state snippets are renamed to match the slot names they
+already had in `slotClasses` (`emptyState` / `loadingState` / `errorState`).
+That frees `loading` and `error` for the state props they are everywhere else
+in the library — the Table can now be told it is loading or has failed, which
+previously only the managed `queryFn` path could do.
+
+| Before (snippet) | After (snippet) | Freed prop             |
+| ---------------- | --------------- | ---------------------- |
+| `empty`          | `emptyState`    | —                      |
+| `loading`        | `loadingState`  | `loading?: boolean`    |
+| `error`          | `errorState`    | `error?: string\|null` |
+
+```svelte
+<!-- before -->
+<Table {items} {columns}>
+  {#snippet empty()}<tr><td colspan="99">Nothing here</td></tr>{/snippet}
+</Table>
+
+<!-- after — plus the new state props for data you fetch yourself -->
+<Table {items} {columns} loading={pending} error={failure}>
+  {#snippet emptyState()}<tr><td colspan="99">Nothing here</td></tr>{/snippet}
+</Table>
+```
+
+With a managed `queryFn` the table still owns both states and ignores the two
+props (DEV warns).
+
 ## 4. Dialog + Drawer intent
 
 Dialog and Drawer no longer draw a coloured `border-t-[3px]` accent for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.40.4",
+  "version": "6.43.2",
   "description": "Svelte 5 UI component library with Tailwind CSS 4, OKLCH design tokens and zero runtime dependencies",
   "license": "MIT",
   "repository": {
@@ -93,8 +93,8 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@urbicon-ui/i18n": "6.40.4",
-    "@urbicon-ui/shared-types": "6.40.4",
+    "@urbicon-ui/i18n": "6.43.2",
+    "@urbicon-ui/shared-types": "6.43.2",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",