@singlebase/elements 0.1.0

package/dist/elements/account-screen.d.ts

@@ -0,0 +1,99 @@
+import { type PropertyValues } from "lit";
+import { type AuthSettings } from "@singlebase/singlebase-sdk";
+import { SinglebaseFormBase } from "./form-base.js";
+import "./uploader.js";
+/**
+ * The authenticated account view, laid out exactly as the design mock's
+ * isAuthed branch: identity header, profile summary with grouped edit
+ * cards, password section, two-factor, connected accounts and danger zone.
+ *
+ * Two-factor setup and account deletion have no backing operation yet, so
+ * they are hidden (SHOW_TWO_FACTOR, SHOW_DELETE_ACCOUNT). Listing and
+ * unlinking providers isn't supported either, and says so; connecting
+ * a *new* provider is supported, so those tiles are live.
+ */
+export declare class SinglebaseAccountScreen extends SinglebaseFormBase {
+    accessor logoText: string;
+    /** A logo image, used instead of `logo-text` when set. */
+    accessor logoUrl: string;
+    accessor settings: AuthSettings | null;
+    accessor nonceStorageKey: string;
+    private accessor editMode;
+    private accessor toast;
+    private accessor photoBusy;
+    /** A photo URL that failed to load, so the initials show instead of a broken image. */
+    private accessor photoFailed;
+    private accessor profileSaved;
+    private accessor passSaved;
+    private accessor profileError;
+    private accessor newPassError;
+    private accessor deleteStage;
+    private accessor confirmText;
+    private accessor dFirst;
+    private accessor dLast;
+    private accessor dPhone;
+    private accessor dEmail;
+    private accessor emailStep;
+    private accessor dNewEmail;
+    private accessor emailCode;
+    private accessor emailError;
+    private accessor emailSaved;
+    private accessor curPass;
+    private accessor newPass;
+    private accessor confirmPass;
+    private settingsCtl;
+    private flashTimer?;
+    private uidBase;
+    private uid;
+    willUpdate(changed: PropertyValues): void;
+    disconnectedCallback(): void;
+    private flash;
+    /** Matches the guest screens: image when given one, else the text label. */
+    private renderLogo;
+    private get user();
+    private get fullName();
+    private get initials();
+    private uploadClientFor;
+    private uploadClientCache;
+    /**
+     * The upload API bound to the same dispatcher as this widget's auth client,
+     * so the photo goes to the same project with the same bearer — including on
+     * a page where this widget was given its own `.client`.
+     */
+    private get uploadClient();
+    private onChoosePhoto;
+    private onPhotoSelected;
+    /** The server has set the photo; read the account back to get its URL. */
+    private onPhotoUploaded;
+    private onPhotoProblem;
+    private startProfileEdit;
+    private onSaveProfile;
+    private startPassEdit;
+    private onChangePass;
+    private startEmailEdit;
+    /**
+     * Step one: ask for a code. The code goes to the address on file, not to
+     * the new one — that is what proves the person asking already controls the
+     * account rather than merely knowing an address.
+     */
+    private onRequestEmailCode;
+    /** Step two: confirm the code together with the new address. */
+    private onConfirmEmailChange;
+    private renderEmailSection;
+    private onSignOut;
+    private onConnectProvider;
+    private get availableProviders();
+    private renderIdentity;
+    private renderProfileSection;
+    private renderPasswordSection;
+    /** Layout preserved from the mock; no enrolment operation exists yet. */
+    private renderTwoFactorSection;
+    private renderConnectedSection;
+    private renderDangerSection;
+    protected render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "singlebase-authui-account": SinglebaseAccountScreen;
+    }
+}

package/dist/elements/auth-screen.d.ts

@@ -0,0 +1,215 @@
+import { nothing, type PropertyValues } from "lit";
+import { type AuthSettings } from "@singlebase/singlebase-sdk";
+import { SinglebaseElementBase } from "./base.js";
+import "./account-screen.js";
+import "./buttons.js";
+/** Screens a signed-out visitor may reach. */
+export type GuestScreen = "signin" | "signup" | "forgot" | "verify" | "otp" | "newpass" | "invite";
+/** Screens that require a live session. */
+export type ProtectedScreen = "account";
+/** Every value `screen` accepts. "oauth-callback" is entered by URL, not by hand. */
+export type Screen = GuestScreen | ProtectedScreen | "oauth-callback";
+export declare function isGuestScreen(value: string): value is GuestScreen;
+export declare function isProtectedScreen(value: string): value is ProtectedScreen;
+export declare function isScreen(value: string): value is Screen;
+/**
+ * The complete auth widget: routes among signin, signup, recovery, one-time
+ * code, invite and OAuth-callback views (spec: AuthScreen), and renders the
+ * design's full card chrome — brand panel, logo, method accordion, step bar,
+ * banner/notice, actions and footer.
+ *
+ * Structure and styling follow project/AuthWidget.dc.html; the individual
+ * sb-* form elements remain available for hosts that want to compose their
+ * own screen instead of using this one.
+ */
+export declare class SinglebaseAuthScreen extends SinglebaseElementBase {
+    static styles: import("lit").CSSResult[];
+    accessor initialScreen: Screen;
+    /**
+     * Two-way screen binding for SPA routers: set it to deep-link a screen,
+     * read it (or listen for `singlebase-screen-change`) to mirror the widget
+     * into your URL. `goto()` is the imperative form.
+     */
+    accessor screen: Screen | "";
+    /**
+     * By default the widget swaps to the account view once authenticated.
+     * SPAs usually want to route away and unmount instead — set this and the
+     * widget renders nothing when signed in, leaving navigation to the host.
+     */
+    accessor noAccountView: boolean;
+    accessor settings: AuthSettings | null;
+    accessor authEnabled: boolean;
+    accessor allowEmailSignin: boolean;
+    accessor allowEmailSignup: boolean;
+    accessor allowEmailOtp: boolean;
+    accessor allowOauth: boolean;
+    accessor allowAccountCreation: boolean;
+    accessor layout: "card" | "split";
+    accessor oauthPlacement: "top" | "bottom";
+    accessor stepped: boolean;
+    /**
+     * Branding is the host's, so these default to empty and the corresponding
+     * slots simply do not render. ("KEYRING" and friends were the fictional
+     * brand in the design mock — they must never ship as defaults.)
+     */
+    accessor logoText: string;
+    /**
+     * A logo image, used instead of `logo-text` when set. `logo-text` is still
+     * worth supplying alongside it — it becomes the image's alt text.
+     */
+    accessor logoUrl: string;
+    accessor brandLine: string;
+    accessor brandFoot: string;
+    accessor signInTitle: string;
+    /**
+     * The "Auth by Singlebase" credit under the card. On by default; turn it
+     * off with branding="false", exactly like the allow-* flags.
+     *
+     * It is a plain link — no pixel, no beacon, no request of any kind. A
+     * third-party network call originating from a sign-in form is the sort of
+     * thing that fails a security review, and deservedly.
+     */
+    accessor branding: boolean;
+    /**
+     * Where to send the user once a session exists. Same-origin only — an
+     * absolute URL pointing anywhere else is refused, because a login widget
+     * that forwards to an attacker-supplied host is an open redirect.
+     *
+     * When unset, a `?redirect=` (or `?next=`) parameter on the current URL is
+     * used instead, so "you were sent to the login page, now go back where you
+     * were headed" works without the host wiring anything.
+     */
+    accessor redirectUrl: string;
+    /** Shown as "Terms" in the consent line under the primary action. */
+    accessor tosUrl: string;
+    /** Shown as "Privacy" in the consent line under the primary action. */
+    accessor privacyUrl: string;
+    /** Where the OAuth nonce is stashed between starting a flow and returning. */
+    accessor nonceStorageKey: string;
+    accessor inviteEmail: string;
+    accessor inviteOrg: string;
+    /** Invite code carried by the invite link; when absent the widget asks for it. */
+    accessor inviteCode: string;
+    private accessor step;
+    private accessor method;
+    private accessor email;
+    private accessor password;
+    private accessor name;
+    private accessor firstName;
+    private accessor lastName;
+    private accessor phone;
+    private accessor newPass;
+    private accessor confirmPass;
+    private accessor code;
+    private accessor verifyNext;
+    private accessor loading;
+    private accessor banner;
+    private accessor notice;
+    private accessor emailError;
+    private accessor passError;
+    private accessor newPassError;
+    private accessor attempts;
+    private accessor needsMfaCode;
+    private settingsCtl;
+    private bridge;
+    private uidBase;
+    private uid;
+    willUpdate(changed: PropertyValues): void;
+    disconnectedCallback(): void;
+    private gotoUnsubscribe?;
+    private gotoClient;
+    /**
+     * Subscribes to auth.goto() so a host can drive every widget on the page
+     * with one call. Bound here rather than in connectedCallback because the
+     * app usually creates its SinglebaseAuth() instance *after* the widget
+     * upgrades — at connect time there is often no client to subscribe to yet.
+     */
+    private bindGoto;
+    /** Shows a screen. The SPA-facing counterpart of the `screen` property. */
+    goto(screen: Screen): void;
+    private get cfg();
+    /** The screen the host asked for, before any guarding is applied. */
+    private get requestedScreen();
+    /**
+     * Resolves the screen actually rendered.
+     *
+     * This is the single place navigation is decided, so a protected screen
+     * cannot be reached by setting an attribute, editing the URL, or calling
+     * goto() — every route runs through the same auth check. The guest
+     * fallbacks below additionally reflect what the project has enabled.
+     */
+    private get activeScreen();
+    /** True when a signed-in user is sitting on a guest screen (spec: offer continue/sign out). */
+    private get showsSignedInInterstitial();
+    /**
+     * The post-login destination, or null when there is none.
+     *
+     * Only same-origin targets are accepted. A login widget that forwards to
+     * an attacker-chosen host is a textbook open redirect, and the `redirect`
+     * parameter it reads comes straight off the URL bar, so it is untrusted
+     * input by definition.
+     */
+    private get redirectTarget();
+    private get redirectParam();
+    /** Navigates to the post-login destination if there is a safe one. */
+    private followRedirect;
+    private get isOAuthCallback();
+    private accessor callbackDone;
+    /** Strips the provider's parameters so a reload cannot replay the exchange. */
+    private cleanCallbackUrl;
+    /**
+     * Completes the provider round trip. Runs once per landing: the URL is
+     * cleaned immediately so a refresh cannot resend a single-use access code.
+     */
+    private handleOAuthCallback;
+    /** The small logo above a screen title: image when given one, else text. */
+    private renderLogo;
+    /** The larger logo in the split layout's brand panel. */
+    private renderBrandMark;
+    private renderBranding;
+    /** Every screen renders inside this, so the credit appears once and only once. */
+    private panel;
+    private renderOAuthCallback;
+    private setScreen;
+    private withLoading;
+    private describeError;
+    private get codeValue();
+    private onSubmit;
+    private abortController;
+    private signal;
+    private onCodeInput;
+    private onCodePaste;
+    private fillCode;
+    private onResend;
+    private goBack;
+    private titleFor;
+    private subFor;
+    private ctaFor;
+    private stepPct;
+    private renderPrimary;
+    private renderEmailField;
+    private renderPasswordField;
+    private renderCodeRow;
+    /** The email/password method accordion body for signin, signup and otp. */
+    private renderEmailMethodBody;
+    private renderAccordion;
+    private renderScreenBody;
+    private renderGuest;
+    private renderBlocked;
+    /**
+     * Shown when a signed-in visitor lands on a guest screen. Rather than
+     * presenting a sign-in form to someone already signed in, offer the two
+     * things they could actually want: carry on, or switch accounts.
+     */
+    private renderSignedIn;
+    private onContinue;
+    private onInterstitialSignOut;
+    /** The Terms/Privacy consent line, rendered only when the host supplies a link. */
+    private renderConsent;
+    protected render(): import("lit").TemplateResult<1> | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "singlebase-authui": SinglebaseAuthScreen;
+    }
+}

package/dist/elements/base.d.ts

@@ -0,0 +1,69 @@
+import { LitElement, type PropertyValues } from "lit";
+import { type AuthUIConfig } from "@singlebase/core";
+import type { AuthClient, UserProfile } from "@singlebase/singlebase-sdk";
+import { AuthController } from "../controllers/auth-controller.js";
+import { defaultMessages, type SinglebaseAuthMessages } from "../messages.js";
+/**
+ * Base class for every singlebase-* element: resolves an AuthClient, exposes
+ * .messages overrides, and gives subclasses a live AuthController bound to
+ * whichever client won.
+ */
+export declare abstract class SinglebaseElementBase extends LitElement {
+    static styles: import("lit").CSSResult[];
+    accessor client: AuthClient | null;
+    accessor messages: Partial<SinglebaseAuthMessages>;
+    /**
+     * theme/density/field-style are plain reflected attributes so a composing
+     * parent can forward them verbatim to the singlebase-* children it renders.
+     * CSS custom properties inherit through shadow boundaries on their own,
+     * but an *attribute* selector like :host([theme="dark"]) only matches
+     * the element that actually carries the attribute, so it must be
+     * explicitly propagated down the composition tree.
+     */
+    accessor theme: "light" | "dark" | undefined;
+    accessor density: "comfortable" | "compact" | undefined;
+    /**
+     * Input chrome: boxed (default) or a single bottom rule. Reflected for the
+     * same reason as theme/density — the CSS is an attribute selector.
+     */
+    accessor fieldStyle: "outline" | "underline" | undefined;
+    protected auth: AuthController;
+    /**
+     * Resolution order: an explicit `.client`, then the page's default
+     * SinglebaseClient()'s auth.
+     *
+     * That fallback is what lets several widgets sit on one page — a header
+     * sign-in, a modal, an account panel — and share one session with no
+     * wiring, since SinglebaseClient() is cached per project. A page talking to
+     * two projects sets `.client` on the widgets belonging to the second.
+     *
+     * Reading `.auth` is also what *constructs* auth: a page that only drops
+     * in a widget initializes it with no bootstrap code at all.
+     */
+    get resolvedClient(): AuthClient | null;
+    /** Page-wide UI config from SinglebaseClient({ authui }), if there is one. */
+    get uiConfig(): AuthUIConfig | null;
+    /**
+     * Config messages sit *under* the element's own, so a page-wide translation
+     * can be overridden per widget without repeating the whole bag.
+     */
+    get msg(): SinglebaseAuthMessages;
+    /** Config keys already applied, so a later render does not fight the host. */
+    private appliedConfig;
+    /**
+     * Copies the page-wide config onto this element.
+     *
+     * An attribute present in markup always wins — that is the whole precedence
+     * rule, and it is checked per key rather than wholesale, so a widget can
+     * override one thing and inherit the rest. Keys the element does not have
+     * are skipped, which is how one config can serve every singlebase-authui-*
+     * element without any of them knowing about the others.
+     */
+    protected applyUIConfig(): void;
+    isAuthenticated(): boolean;
+    getUser(): UserProfile | null;
+    refreshSession(): Promise<import("@singlebase/singlebase-sdk").AuthSession | undefined>;
+    logout(): Promise<void>;
+    willUpdate(changed: PropertyValues): void;
+}
+export { defaultMessages };

package/dist/elements/buttons.d.ts

@@ -0,0 +1,45 @@
+import { nothing, type PropertyValues } from "lit";
+import type { AuthSettings, OAuthIntent } from "@singlebase/singlebase-sdk";
+import { SinglebaseFormBase } from "./form-base.js";
+export type ButtonsType = "signout" | "oauth" | "link";
+/**
+ * The widget's action buttons, selected with `type`:
+ *
+ *   <singlebase-authui-buttons type="signout"></singlebase-authui-buttons>
+ *   <singlebase-authui-buttons type="oauth" intent="signup"></singlebase-authui-buttons>
+ *   <singlebase-authui-buttons type="link" provider="github"></singlebase-authui-buttons>
+ *
+ * They live under one tag rather than three because they are the same thing
+ * from a host's point of view — a button that performs one auth action — and
+ * every custom element name is a global, unversioned claim on any page this
+ * widget is dropped into.
+ */
+export declare class SinglebaseAuthButtons extends SinglebaseFormBase {
+    accessor type: ButtonsType;
+    /** oauth: which flow the provider buttons start. */
+    accessor intent: OAuthIntent;
+    /** link: the provider to connect to the signed-in account. */
+    accessor provider: string;
+    /** link: display name, when it differs from the provider id. */
+    accessor providerName: string;
+    /** Inside a card that already supplies chrome, drop this element's own. */
+    accessor embedded: boolean;
+    accessor settings: AuthSettings | null;
+    accessor nonceStorageKey: string;
+    private settingsCtl;
+    willUpdate(changed: PropertyValues): void;
+    private get effectiveSettings();
+    private get providers();
+    /** Shared by the oauth and link flows: nonce, start, redirect. */
+    private startOAuth;
+    private renderOAuth;
+    private renderLink;
+    private onSignOut;
+    private renderSignOut;
+    protected render(): import("lit").TemplateResult<1> | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "singlebase-authui-buttons": SinglebaseAuthButtons;
+    }
+}

package/dist/elements/display.d.ts

@@ -0,0 +1,51 @@
+import { nothing, type PropertyValues } from "lit";
+import { SinglebaseElementBase } from "./base.js";
+/**
+ * Displays one value from the signed-in profile, as text or as an avatar.
+ *
+ *   Hello <singlebase-authui-display path="first_name" fallback="there"></singlebase-authui-display>
+ *   <singlebase-authui-display avatar></singlebase-authui-display>
+ *
+ * Three rules shape the behaviour:
+ *
+ *  - While auth state is still loading it renders nothing. Showing the
+ *    fallback first would mean every signed-in visitor watches "Hello there"
+ *    flip to "Hello Ada" on each page load.
+ *  - Values resolve against `user_profile` and nothing else. The element
+ *    deliberately cannot reach session or token data, which must never be
+ *    written into the DOM.
+ *  - Values are rendered as text, never as markup. Fields like first_name are
+ *    supplied by the user at signup, so they are untrusted by definition.
+ */
+export declare class SinglebaseAuthDisplay extends SinglebaseElementBase {
+    static styles: import("lit").CSSResult[];
+    /**
+     * Dot-notated path into the profile: "first_name", "metadata.tier". In
+     * avatar mode it names the image field and defaults to "profile_photo".
+     */
+    accessor path: string;
+    /** Shown when signed out, or when the value is empty. Text mode only. */
+    accessor fallback: string;
+    /** Render an image with an initials fallback instead of text. */
+    accessor avatar: boolean;
+    /**
+     * Alternative text for the avatar image. Left empty the image is treated as
+     * decorative, which is right when a name sits beside it — pass a value only
+     * when the avatar is the sole identifier.
+     */
+    accessor alt: string;
+    /** Set when the image 404s, so a dead URL falls back to initials. */
+    private accessor imageFailed;
+    willUpdate(changed: PropertyValues): void;
+    private get profile();
+    /** The resolved value as a string, or "" when there is nothing to show. */
+    private get textValue();
+    private get avatarSrc();
+    protected render(): import("lit").TemplateResult<1> | typeof nothing;
+    private renderAvatar;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "singlebase-authui-display": SinglebaseAuthDisplay;
+    }
+}

package/dist/elements/form-base.d.ts

@@ -0,0 +1,23 @@
+import { SinglebaseElementBase } from "./base.js";
+export type FormPhase = "idle" | "submitting" | "success" | "error";
+/**
+ * Adds the spec's required cross-cutting form behavior to SinglebaseElementBase:
+ * idle/submitting/success/error phase, a form-level error message, disabled
+ * controls while submitting, an aria-live status region, and cancellation of
+ * in-flight work on disconnect.
+ */
+export declare abstract class SinglebaseFormBase extends SinglebaseElementBase {
+    protected accessor phase: FormPhase;
+    protected accessor formError: string;
+    protected accessor noticeMessage: string;
+    protected abortController: AbortController | null;
+    disconnectedCallback(): void;
+    protected get signal(): AbortSignal;
+    /** Runs task, tracking idle→submitting→success/error and mapping errors to a message. */
+    protected run(task: () => Promise<void>): Promise<void>;
+    private isAbortError;
+    protected describeError(error: unknown): string;
+    protected get submitting(): boolean;
+    /** aria-live region for async status — spec requires one per form. */
+    protected renderStatus(): import("lit").TemplateResult<1>;
+}

package/dist/elements/guard.d.ts

@@ -0,0 +1,65 @@
+import { type Predicate } from "@singlebase/core";
+import { SinglebaseElementBase } from "./base.js";
+export type GuardState = "loading" | "authenticated" | "unauthenticated";
+/**
+ * Renders content conditionally on auth state, and optionally on a predicate
+ * over the signed-in profile.
+ *
+ * Two shapes, because wrapping a single line of markup in a slotted <div> is
+ * a lot of ceremony:
+ *
+ *   <!-- long form: one guard, several states -->
+ *   <singlebase-authui-guard>
+ *     <div slot="loading">Checking…</div>
+ *     <div slot="authenticated">Welcome back</div>
+ *     <div slot="unauthenticated"><singlebase-authui></singlebase-authui></div>
+ *   </singlebase-authui-guard>
+ *
+ *   <!-- short form: the guard itself carries the state -->
+ *   <singlebase-authui-guard slot="loading">Checking…</singlebase-authui-guard>
+ *
+ * With a predicate it also filters on the profile:
+ *
+ *   <singlebase-authui-guard slot="authenticated" predicate='{"roles":{"$in":["admin"]}}'>
+ *     <admin-panel></admin-panel>
+ *   </singlebase-authui-guard>
+ *
+ * A predicate only ever narrows the *authenticated* state: a signed-out
+ * visitor is unauthenticated whether or not a filter is present, so a guard
+ * can never leak content by failing open.
+ */
+export declare class SinglebaseAuthGuard extends SinglebaseElementBase {
+    /**
+     * Short form. When set, every child of this guard belongs to that state and
+     * no per-child `slot` attributes are needed.
+     *
+     * Note this reuses the standard `slot` attribute name, which is inert here:
+     * the guard is not itself inside another shadow root's slot, so the name is
+     * free to mean "the state these children belong to".
+     */
+    accessor slot: string;
+    /**
+     * One-level, Mongo-style filter over the signed-in `user_profile`.
+     * Dot notation reaches nested values; see core's predicate module for the
+     * supported operators.
+     */
+    accessor predicate: Predicate | null;
+    /**
+     * What to show when the user is signed in but the predicate does not match.
+     * Defaults to "unauthenticated" so a filtered guard degrades to the
+     * signed-out branch; set "hidden" to render nothing at all.
+     */
+    accessor onMismatch: "unauthenticated" | "hidden";
+    private warnedFor;
+    protected createRenderRoot(): this;
+    /** The state this guard currently resolves to, after applying the predicate. */
+    get activeState(): GuardState | "hidden";
+    /** Surfaces a malformed predicate once, rather than silently never matching. */
+    private warnOnce;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "singlebase-authui-guard": SinglebaseAuthGuard;
+    }
+}