selfstore 1.8.10 → 1.8.11

package/README.md

@@ -162,7 +162,7 @@ too, as subpaths of the same install:
 |---|---|---|
 | `selfstore` | the simple store + backup files | almost always: start here |
 | `selfstore/flows` | the user journeys (connect a destination, share panel, join an invitation) as headless, tested state machines | you are building the connect/share/join UI and want the ordering and failure rules - one popup per gesture, password proven before attach, merge by default - already right |
-| `selfstore/widgets` | the same journeys as drop-in web components (`<selfstore-connect>`, `<selfstore-gate>`, `<selfstore-destination>`, `<selfstore-share>`, `<selfstore-join>`) - framework-free, themable via CSS custom properties and `::part()`, reworded/localized via a `labels` map | you want the screens ready-made and your app's look on top |
+| `selfstore/widgets` | the same journeys as drop-in web components (`<selfstore-storage>` for the whole journey in one tag, or `<selfstore-connect>`, `<selfstore-gate>`, `<selfstore-destination>`, `<selfstore-account>`, `<selfstore-share>`, `<selfstore-join>` on their own) - framework-free, themable via CSS custom properties and `::part()`, reworded/localized via a `labels` map | you want the screens ready-made and your app's look on top |
 | `selfstore/advanced` | the pull-model store (`createLocalStore`), custom `BackupTarget`s, caches, headless status derivation, functional codec | your state lives in its own reactive model (Svelte runes, Redux), or you are writing a destination (S3, your KV...) |
 | `selfstore/groups` | passwordless group encryption: per-member identities, sealed envelopes, signed membership manifests | several PEOPLE share one encrypted store without a shared password ([PEERS.md](./PEERS.md)) |
 | `selfstore/sync` | the bare merge engine (HLC + per-collection strategies, no CRDT runtime) | you only want the algorithm inside your own persistence ([SYNC docs in SPEC.md](./SPEC.md)) |

package/dist/widgets.d.ts

@@ -31,10 +31,13 @@ declare abstract class FlowWidget extends HTMLElement {
     /** Partial override map, merged over the EN defaults (also the i18n hook). */
     get labels(): WidgetLabels;
     set labels(map: WidgetLabels);
-    /** The shipped translation for the page's language, if the widget has one.
-     *  An explicit `lang` on the element (or on any ancestor) wins over the
-     *  document's, which wins over the browser's, so a host that already sets
-     *  `<html lang>` gets translated copy without writing a single label. */
+    /** The language this widget speaks. An explicit `lang` on the element (or on
+     *  any ancestor) wins over the document's, which wins over the browser's, so
+     *  a host that already sets `<html lang>` gets translated copy without
+     *  writing a single label. Also what to hand `Intl` when a widget formats a
+     *  date or a duration itself. */
+    protected langTag(): string;
+    /** The shipped translation for the page's language, if the widget has one. */
     private localized;
     /**
      * The copy for a key, with `{placeholders}` filled in.
@@ -57,7 +60,33 @@ declare abstract class FlowWidget extends HTMLElement {
     /** Hands back whatever the host set before this class existed, then the
      *  subclass reads its attributes and wires itself. Subclasses override this
      *  and call `super.connectedCallback()` FIRST, for that reason. */
+    /**
+     * What the HOST decided before this element could hear it.
+     *
+     * Assigning a property to an element that has not upgraded yet is what every
+     * framework does - the widget bundle is loaded lazily, the assignment is
+     * not - and `upgradeOwnProperties` replays those assignments through the
+     * real setters. Then reading the same knob back from the markup would undo
+     * them: an attribute is a DEFAULT written by the page, a property is a
+     * decision taken by the app, and the decision has to win. A widget reads its
+     * attributes through this set.
+     */
+    protected assigned: Set<string>;
     connectedCallback(): void;
+    /**
+     * An attribute the host has NOT already decided in code, or null.
+     *
+     * Two ways it can have decided, and both have to be caught. It replayed
+     * through `assigned` on connect - or it has not been replayed yet, and its
+     * value is sitting on the element as an own property shadowing this very
+     * accessor. That second case is the one that bit: on upgrade the browser
+     * fires attributeChangedCallback BEFORE connectedCallback, so a widget
+     * writing the attribute through its own setter wrote into the shadowing own
+     * property instead - overwriting the decision it was about to replay.
+     */
+    protected attr(name: string): string | null;
+    /** The same, as a boolean: absent is null, anything but "false" is true. */
+    protected flag(name: string): boolean | null;
     protected emit(name: string, detail?: unknown): void;
     /** Rebuild the body, keeping the focused input's value and focus across the
      *  rebuild (inputs carry data-keep so typing survives a snapshot change). */
@@ -523,7 +552,7 @@ declare class SelfstoreGateElement extends FlowWidget {
      *  `flow` included). Null while the gate is shut. */
     get connect(): SelfstoreConnectElement | null;
     constructor();
-    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    attributeChangedCallback(name: string): void;
     connectedCallback(): void;
     private host;
     private wire;
@@ -673,7 +702,7 @@ declare class SelfstoreStorageElement extends FlowWidget {
     /** Which destination the first-run screen badges as recommended. */
     get recommended(): ConnectKind | null;
     set recommended(v: ConnectKind | null);
-    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    attributeChangedCallback(name: string): void;
     connectedCallback(): void;
     private host;
     /** What the store offers, unless the host said otherwise. */
@@ -681,10 +710,101 @@ declare class SelfstoreStorageElement extends FlowWidget {
     protected view(into: HTMLElement): void;
 }
 
+/**
+ * <selfstore-account>: the storage control in an app's chrome.
+ *
+ *   document.querySelector('selfstore-account').store = store;
+ *
+ * A trigger that states where the data is going, and a short menu that answers
+ * the two questions a header should answer: WHO holds my backup and when was
+ * it last written, and how do I change my mind.
+ *
+ * Why it is short. The panel (<selfstore-destination>) offers four gestures,
+ * which is right for a settings page and wrong for a menu: a header that opens
+ * onto "export a copy / restore a copy / change backup / stop saving here"
+ * asks the user to arbitrate between four irreversible-looking words before
+ * they know what any of them does. So this element keeps exactly two - go to
+ * the settings, where the panel lives, or change backup - and hands the rest
+ * to the page the host already has.
+ *
+ * "Change backup" detaches, and stops there. It does not run a connect journey
+ * of its own: an app that mounts <selfstore-gate> (or <selfstore-storage>)
+ * already has the first-run screen, and a store with no destination is exactly
+ * what that screen is for. One journey, reached the same way whether it is the
+ * first day or a change of mind.
+ */
+
+declare class SelfstoreAccountElement extends FlowWidget {
+    #private;
+    protected defaults(): WidgetLabels;
+    protected packs(): Record<string, WidgetLabels>;
+    constructor();
+    /** The simple store (anything exposing `flowHost`), or a hand-built FlowHost.
+     *  A simple store also answers `account` on its own, so nothing else is
+     *  needed to name who holds the backup. */
+    get store(): StoreLike | null;
+    set store(v: StoreLike | null);
+    get account(): string | null;
+    set account(v: string | null);
+    /** Optional glyph per destination kind, same contract as the connect cards. */
+    get icons(): Partial<Record<ConnectKind, string>>;
+    set icons(v: Partial<Record<ConnectKind, string>> | null);
+    /** Veto on changing backup, which leaves the app with no destination until
+     *  the user picks one. Returns false (or throws) to stop. */
+    get confirmAction(): ((a: DestinationAction) => boolean | Promise<boolean>) | null;
+    set confirmAction(fn: ((a: DestinationAction) => boolean | Promise<boolean>) | null);
+    /** Whether the menu is on screen. Settable, so a host can close it from its
+     *  own router after the settings item navigated away. */
+    get open(): boolean;
+    set open(v: boolean);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** While the menu is open: a clock for the relative time, and the two ways
+     *  out that make it a menu rather than a page - a click anywhere else, and
+     *  Escape. `pointerdown` and not `click`, so the gesture that closes it does
+     *  not also land on whatever was under the menu. Shadow DOM retargets the
+     *  event, so what is asked is the composed path, never `e.target`. */
+    private watch;
+    /** The destination's name. An unknown kind (a host's own target) has no
+     *  shipped name: its own label is a better answer than the raw key. */
+    private named;
+    /** "just now", "3 minutes ago", "yesterday" - in the page's language, from
+     *  Intl rather than from five label keys per language. */
+    private when;
+    /**
+     * The one line under the account. A plain "saved" is the only state this
+     * element words itself, because it is the only one with nothing to do about
+     * it - and the only one where WHEN is the whole information. Everything else
+     * (reconnect, unlock, changes to download) belongs to <selfstore-status>,
+     * which owns both the wording and the button that resolves it.
+     */
+    private line;
+    /** Ask for the settings. The host owns the route, so this only says that it
+     *  was asked - and closes, because a menu that stays open behind a page
+     *  transition reads as a failed click. */
+    private settings;
+    /** Change backup: detach, and let the first-run screen take it from there.
+     *  The data stays; only the destination is let go. */
+    private change;
+    private card;
+    protected view(into: HTMLElement): void;
+    /**
+     * Which side the menu hangs from.
+     *
+     * A header control is usually at the right edge, so the menu hangs right -
+     * and the moment the header wraps on a narrow window, that same control sits
+     * at the LEFT edge and the menu hangs off the screen. Measured rather than
+     * assumed: it hangs left when there is room to the right, and right
+     * otherwise, which lands correctly at both edges without the host declaring
+     * where it put the control.
+     */
+    private anchor;
+}
+
 /** Register the elements as <PREFIX-connect>, <PREFIX-share>, <PREFIX-join>,
  *  <PREFIX-status>, <PREFIX-backups>, <PREFIX-gate> and
  *  <PREFIX-destination> (default prefix 'selfstore'). Safe to call twice;
  *  throws in environments without custom elements (browser code only). */
 declare function defineSelfstoreWidgets(prefix?: string): void;
 
-export { type BackupsAction, type DestinationAction, FlowWidget, SelfstoreBackupsElement, SelfstoreConnectElement, SelfstoreDestinationElement, SelfstoreGateElement, SelfstoreJoinElement, SelfstoreShareElement, SelfstoreStatusElement, SelfstoreStorageElement, type ShareAction, type WebdavPreset, type WidgetLabels, defineSelfstoreWidgets };
+export { type BackupsAction, type DestinationAction, FlowWidget, SelfstoreAccountElement, SelfstoreBackupsElement, SelfstoreConnectElement, SelfstoreDestinationElement, SelfstoreGateElement, SelfstoreJoinElement, SelfstoreShareElement, SelfstoreStatusElement, SelfstoreStorageElement, type ShareAction, type WebdavPreset, type WidgetLabels, defineSelfstoreWidgets };