@excom/provider-storage 0.1.0

package/.rush/temp/chunked-rush-logs/provider-storage.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/chunked-rush-logs/provider-storage.build_docs.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/chunked-rush-logs/provider-storage.build_package-metas.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 34.84205700000007
+}

package/.rush/temp/operation/build_docs/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/.rush/temp/operation/build_docs/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/operation/build_docs/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 43.99502499999994
+}

package/.rush/temp/operation/build_package-metas/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/.rush/temp/operation/build_package-metas/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/build_package-metas/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 101.22544199999993
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/provider-storage": "../../packages/provider-storage:rrFX5s3WCBVNkmNhA28lT/w/Ce6jrCJLmfP50wp4Hns=:"
+}

package/config/rig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}

package/index.ts

@@ -0,0 +1,18 @@
+import { ProviderStorage } from "./provider-storage";
+
+ProviderStorage.define();
+
+export { ProviderStorage };
+export type { ProviderStorageChangedEvent } from "./provider-storage";
+
+type T_HTMLProviderStorageElement = typeof ProviderStorage.CustomElement;
+declare global {
+  interface HTMLProviderStorageElement extends T_HTMLProviderStorageElement {}
+  interface Window {
+    HTMLProviderStorageElement: HTMLProviderStorageElement;
+  }
+  interface HTMLElementTagNameMap {
+    "provider-storage": HTMLProviderStorageElement;
+  }
+}
+export type { HTMLProviderStorageElement };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@excom/provider-storage",
+  "version": "0.1.0",
+  "description": "<provider-storage> custom element",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/kit-logger": "^0.1.0",
+    "@excom/neutron": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/provider-storage"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/provider-storage/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "provider-storage",
+    "neutron",
+    "custom-elements",
+    "localstorage",
+    "sessionstorage"
+  ],
+  "excom": {
+    "packageType": "kit-element"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs",
+    "build:package-metas": "node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs",
+    "build:docs": "node node_modules/@excom/heft-rig/scripts/build-docs.mjs"
+  }
+}

package/provider-storage.ts

@@ -0,0 +1,138 @@
+import { KitLogger } from "@excom/kit-logger";
+import { Neutron, TEvent } from "@excom/neutron";
+
+export type ProviderStorageChangedEvent = TEvent & {
+  type: "provider-storage-changed";
+  detail: {
+    /** The `key-name` whose stored value changed. */
+    keyName: string;
+    /** `provision` before the re-read (`null` when nothing was read). */
+    oldValue: unknown;
+    /** `provision` after the re-read (`null` when absent / not valid JSON). */
+    newValue: unknown;
+  };
+};
+
+type StoreProps = { keyName?: string | null; storeName?: string | null };
+
+const getStore = (storeName?: string | null) =>
+  storeName === "session" ? sessionStorage : localStorage;
+
+/** Read `key-name` out of `store-name` as JSON → provision / state effect. */
+const readStore = ({ keyName, storeName }: StoreProps) => {
+  try {
+    return {
+      provision: JSON.parse(getStore(storeName).getItem(keyName!) || "null"),
+      isSuccess: true,
+      isError: false,
+    };
+  } catch (e) {
+    KitLogger.error("provider-storage", e);
+    return { provision: null, isSuccess: false, isError: true };
+  }
+};
+
+/**
+ * Reads a JSON value out of `localStorage` / `sessionStorage` under
+ * `key-name` into `provision`. Read-only: it never writes. It re-reads
+ * whenever `key-name` / `store-name` is set or changes, and — for
+ * `localStorage` — whenever another tab writes the same key (the
+ * browser's `storage` event). Same-tab writes do not fire `storage`,
+ * so after your own `setItem` re-set `key-name` to force a read.
+ *
+ * @fires provider-storage-changed - Dispatched after a `storage` event
+ *   from another tab for this element's `store-name` + `key-name` (or a
+ *   `clear()` of that store) has been re-read into `provision` — so
+ *   `provision`, `is-success` / `is-error` are already updated when it
+ *   fires. The read also publishes `neutron-provision`, as usual.
+ * @type ProviderStorageChangedEvent
+ */
+export const ProviderStorage = Neutron({
+  tag: "provider-storage",
+  props: {
+    // options
+    /**
+     * @option
+     * Storage key to read. Setting or changing it re-reads immediately
+     * (parsed as JSON; `null` if absent). Removing it clears
+     * `provision` and both states.
+     * @values <storage key>
+     */
+    keyName: String,
+    /**
+     * @option
+     * Which Web Storage area to read. `local` survives the tab / browser
+     * closing and syncs across tabs; `session` is per-tab and gone when
+     * the tab closes. Changing it re-reads `key-name` from the new store.
+     * @values local, session
+     * @default local
+     */
+    storeName: String,
+    // state
+    /**
+     * @provision
+     * `JSON.parse(store.getItem(keyName))`, or `null` if the key is
+     * absent or the read failed. Not reflected as an attribute.
+     */
+    provision: Object,
+    /**
+     * @state
+     * The last read (parse) succeeded — including a legitimately absent
+     * key (`provision` is `null`, not an error).
+     */
+    isSuccess: Boolean,
+    /**
+     * @state
+     * `JSON.parse` threw on the last read (the stored value isn't valid
+     * JSON). `provision` is `null`.
+     */
+    isError: Boolean,
+  },
+})
+  .defineMethods({
+    // `storage` fires in *other* tabs only, for every key of every store.
+    _handleStorage: (
+      { keyName, storeName, provision }: StoreProps & { provision: unknown },
+      e: StorageEvent
+    ) => {
+      if (!keyName || e.storageArea !== getStore(storeName)) return null;
+      // `key === null` is `clear()`; it took this key with it
+      if (e.key !== null && e.key !== keyName) return null;
+      const next = readStore({ keyName, storeName });
+      return {
+        ...next,
+        emit: [
+          "provider-storage-changed",
+          {
+            detail: {
+              keyName,
+              oldValue: provision,
+              newValue: next.provision,
+            },
+          },
+        ],
+      };
+    },
+  })
+  // Tracked listener: Neutron drops it on disconnect and restores it on
+  // reconnect / move, so no `isMoving` bookkeeping here.
+  .onConnected(
+    // @ts-ignore TODO defineMethods
+    ({ _handleStorage }) => ({
+      addListener: ["storage", _handleStorage, { target: window }],
+    })
+  )
+  // One read per batch, whichever of the two changed (including first mount).
+  .onEffect(["keyName", "storeName"], ({ keyName, storeName }, previous) =>
+    keyName
+      ? readStore({ keyName, storeName })
+      : // `key-name` removed: nothing to show
+        "keyName" in previous && {
+          provision: null,
+          isSuccess: false,
+          isError: false,
+        }
+  );
+
+// <provider-storage key-name="results"></provider-storage>
+// <provider-storage key-name="draft" store-name="session"></provider-storage>

package/rush-logs/provider-storage.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/provider-storage.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/rush-logs/provider-storage.build_docs.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:docs" command, so caching has been disabled.

package/rush-logs/provider-storage.build_docs.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/rush-logs/provider-storage.build_package-metas.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:package-metas" command, so caching has been disabled.

package/rush-logs/provider-storage.build_package-metas.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/support/custom-elements.json

@@ -0,0 +1,167 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "provider-storage.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ProviderStorage",
+          "customElement": true,
+          "tagName": "provider-storage",
+          "description": "The `key-name` whose stored value changed.",
+          "attributes": [
+            {
+              "name": "key-name",
+              "type": {
+                "text": "string"
+              },
+              "description": "Storage key to read. Setting or changing it re-reads immediately (parsed as JSON; `null` if absent). Removing it clears `provision` and both states.",
+              "fieldName": "keyName",
+              "values": [
+                "<storage key>"
+              ]
+            },
+            {
+              "name": "store-name",
+              "type": {
+                "text": "string"
+              },
+              "description": "Which Web Storage area to read. `local` survives the tab / browser closing and syncs across tabs; `session` is per-tab and gone when the tab closes. Changing it re-reads `key-name` from the new store.",
+              "fieldName": "storeName",
+              "default": "local",
+              "values": [
+                "local, session"
+              ]
+            },
+            {
+              "name": "is-success",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "The last read (parse) succeeded — including a legitimately absent key (`provision` is `null`, not an error).",
+              "fieldName": "isSuccess"
+            },
+            {
+              "name": "is-error",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "`JSON.parse` threw on the last read (the stored value isn't valid JSON). `provision` is `null`.",
+              "fieldName": "isError"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "keyName",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Storage key to read. Setting or changing it re-reads immediately (parsed as JSON; `null` if absent). Removing it clears `provision` and both states.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "storeName",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Which Web Storage area to read. `local` survives the tab / browser closing and syncs across tabs; `session` is per-tab and gone when the tab closes. Changing it re-reads `key-name` from the new store.",
+              "default": "local",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "provision",
+              "type": {
+                "text": "object"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "`JSON.parse(store.getItem(keyName))`, or `null` if the key is absent or the read failed. Not reflected as an attribute.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isSuccess",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "The last read (parse) succeeded — including a legitimately absent key (`provision` is `null`, not an error).",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isError",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "`JSON.parse` threw on the last read (the stored value isn't valid JSON). `provision` is `null`.",
+              "_neutron": {
+                "surface": "state"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "provider-storage-changed",
+              "description": "Dispatched after a `storage` event from another tab for this element's `store-name` + `key-name` (or a `clear()` of that store) has been re-read into `provision` — so `provision`, `is-success` / `is-error` are already updated when it fires. The read also publishes `neutron-provision`, as usual.",
+              "type": {
+                "text": "ProviderStorageChangedEvent",
+                "expanded": "CustomEvent & { type: \"provider-storage-changed\"; detail: { keyName: string; oldValue: unknown; newValue: unknown; }; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "provisions": [
+              {
+                "name": "provision",
+                "type": {
+                  "text": "object"
+                },
+                "description": "`JSON.parse(store.getItem(keyName))`, or `null` if the key is absent or the read failed. Not reflected as an attribute.",
+                "fieldName": "provision"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ProviderStorage",
+          "declaration": {
+            "name": "ProviderStorage",
+            "module": "provider-storage.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "provider-storage",
+          "declaration": {
+            "name": "ProviderStorage",
+            "module": "provider-storage.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/simple.html

@@ -0,0 +1,18 @@
+<div>
+  <event-handler role="button" fire-event="demo-seed-storage">
+    Seed localStorage &amp; re-read
+  </event-handler>
+  <provider-storage></provider-storage>
+  <output>Not read yet — click above.</output>
+  <small role="note">Same-tab writes only show up after
+    <code>key-name</code> is re-set; a write from another tab is picked up
+    live.</small>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    :scope {
+      @on demo-seed-storage (handle: seedDemoStorage);
+      @on neutron-provision (handle: setOutputFromElementData);
+    }
+  </quark-sheet>
+</div>

package/support/dist-docs/provider-storage.md

@@ -0,0 +1,118 @@
+# provider-storage
+
+Read a JSON value out of `localStorage` / `sessionStorage` into `provision`,
+declaratively — and keep it in sync across tabs. No app JS required to display
+cached client state.
+
+## Features
+
+- **Declarative read** Point `key-name` at a storage key and read the result
+- **Local or session** `store-name` picks `localStorage` (default) /
+  `sessionStorage`
+- **Live across tabs** A write from another tab re-reads and fires
+  `provider-storage-changed`
+- **Reactive to attributes** Changing `key-name` / `store-name` re-reads
+  immediately
+- **Tiny, read-only** Never writes
+
+## Installation
+
+
+`@excom/provider-storage` v0.1.0
+
+```bash
+pnpm add @excom/provider-storage
+```
+
+```bash
+npm install @excom/provider-storage
+```
+
+```bash
+yarn add @excom/provider-storage
+```
+
+### Import
+
+```ts
+import "@excom/provider-storage";
+```
+
+
+
+## Usage
+
+```html
+<provider-storage key-name="user-preferences"></provider-storage>
+<provider-storage key-name="checkout-draft" store-name="session"></provider-storage>
+```
+
+**Read-only.** It reads on every `key-name` / `store-name` set/change and never
+writes. Removing `key-name` clears `provision` and both states.
+
+**Live across tabs, not within one.** Browsers fire `storage` only in *other*
+tabs, so:
+
+- A write from another tab (or a `clear()` there) re-reads and fires
+  `provider-storage-changed` — no app code needed. `sessionStorage` is
+  per-tab, so this only applies to `store-name="local"`.
+- A write by your own app code (`localStorage.setItem(...)`) in the same tab
+  won't appear until you re-trigger a read — re-set `key-name` (e.g. to `""`
+  and back) after writing.
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `key-name` | option | `string` |  | `<storage key>` | Storage key to read. Setting or changing it re-reads immediately (parsed as JSON; `null` if absent). Removing it clears `provision` and both states. |
+| `store-name` | option | `string` | `"local"` | `local, session` | Which Web Storage area to read. `local` survives the tab / browser closing and syncs across tabs; `session` is per-tab and gone when the tab closes. Changing it re-reads `key-name` from the new store. |
+| `is-success` | state | `boolean` |  |  | The last read (parse) succeeded — including a legitimately absent key (`provision` is `null`, not an error). |
+| `is-error` | state | `boolean` |  |  | `JSON.parse` threw on the last read (the stored value isn't valid JSON). `provision` is `null`. |
+
+#### Provision
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provision` | `object` | `JSON.parse(store.getItem(keyName))`, or `null` if the key is absent or the read failed. Not reflected as an attribute. |
+
+#### Fires
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provider-storage-changed` | `ProviderStorageChangedEvent` (`CustomEvent & { type: "provider-storage-changed"; detail: { keyName: string; oldValue: unknown; newValue: unknown; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched after a `storage` event from another tab for this element's `store-name` + `key-name` (or a `clear()` of that store) has been re-read into `provision` — so `provision`, `is-success` / `is-error` are already updated when it fires. The read also publishes `neutron-provision`, as usual. |
+
+
+
+### Examples
+
+#### Seed & re-read
+
+Since this element never writes, the demo below seeds a value from a button
+(re-setting `key-name` afterward to force the same-tab re-read) so you can see
+it work without opening devtools. Open this page in a second tab and click
+there too — this tab updates on its own.
+
+
+```html
+<div>
+  <event-handler role="button" fire-event="demo-seed-storage">
+    Seed localStorage &amp; re-read
+  </event-handler>
+  <provider-storage></provider-storage>
+  <output>Not read yet — click above.</output>
+  <small role="note">Same-tab writes only show up after
+    <code>key-name</code> is re-set; a write from another tab is picked up
+    live.</small>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    :scope {
+      @on demo-seed-storage (handle: seedDemoStorage);
+      @on neutron-provision (handle: setOutputFromElementData);
+    }
+  </quark-sheet>
+</div>
+```

package/support/docs/README.md

@@ -0,0 +1,55 @@
+# provider-storage
+
+Read a JSON value out of `localStorage` / `sessionStorage` into `provision`,
+declaratively — and keep it in sync across tabs. No app JS required to display
+cached client state.
+
+## Features
+
+- **Declarative read** Point `key-name` at a storage key and read the result
+- **Local or session** `store-name` picks `localStorage` (default) /
+  `sessionStorage`
+- **Live across tabs** A write from another tab re-reads and fires
+  `provider-storage-changed`
+- **Reactive to attributes** Changing `key-name` / `store-name` re-reads
+  immediately
+- **Tiny, read-only** Never writes
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+```html
+<provider-storage key-name="user-preferences"></provider-storage>
+<provider-storage key-name="checkout-draft" store-name="session"></provider-storage>
+```
+
+**Read-only.** It reads on every `key-name` / `store-name` set/change and never
+writes. Removing `key-name` clears `provision` and both states.
+
+**Live across tabs, not within one.** Browsers fire `storage` only in *other*
+tabs, so:
+
+- A write from another tab (or a `clear()` there) re-reads and fires
+  `provider-storage-changed` — no app code needed. `sessionStorage` is
+  per-tab, so this only applies to `store-name="local"`.
+- A write by your own app code (`localStorage.setItem(...)`) in the same tab
+  won't appear until you re-trigger a read — re-set `key-name` (e.g. to `""`
+  and back) after writing.
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Seed & re-read
+
+Since this element never writes, the demo below seeds a value from a button
+(re-setting `key-name` afterward to force the same-tab re-read) so you can see
+it work without opening devtools. Open this page in a second tab and click
+there too — this tab updates on its own.
+
+<include-content data-demo="simple"></include-content>