@ghub/identity-chrome 0.1.0 → 0.3.0

package/README.md

@@ -1,10 +1,10 @@
 # @ghub/identity-chrome
 
 The shared header controls of the Gelhaus Solutions products: the apps picker and the
-account popup. This version is the part with no markup in it: the browser half (what the
-controls know, what they keep, what they do when Identity cannot be reached) and the server
-half (a product's own server asking GPlatform Identity). The Web Component and the React
-wrapper come with the design.
+account popup. Two custom elements with shadow DOM (`<gp-apps>`, `<gp-account>`) and React
+wrappers for them; the browser half under both (what the controls know, what they keep, what
+they do when Identity cannot be reached); and the server half (a product's own server asking
+GPlatform Identity).
 
 Nothing here depends on a product signing in through Identity. A product that has not
 adopted it uses the same package the same way.
@@ -62,6 +62,101 @@ A one-off push of a product's users (`chrome.seed(emails)`) is refused unless st
 opened a window for it on Identity's product screen, and `chrome.remove(emails)` says people
 no longer have access.
 
+## The two controls
+
+```ts
+import { createChromeCore, defineChromeElements } from "@ghub/identity-chrome";
+
+defineChromeElements(); // <gp-apps> and <gp-account>, each once; a no-op on a server
+
+const apps = document.querySelector("gp-apps")!;
+apps.core = chrome; // the core above: one fetch and one cache behind both
+
+const account = document.querySelector("gp-account")!;
+account.core = chrome;
+account.product = "GAdvisory"; // your own name, from your catalogue entry
+account.person = { name: user.name, email: user.email, id: user.id, avatarUrl: user.picture };
+account.organisations = [{ id: "org_1", name: "Hafen Labs", role: "Admin", active: true }];
+account.onSwitch = async (id) => switchOrganisation(id); // reject when it did not switch
+account.onSignOut = async () => {
+  await signOut(); // reject when it failed: the popup says they are still signed in
+  location.assign("/"); // you navigate; as this resolves the element forgets the kept list
+};
+```
+
+Everything is a property, because a core, a person and a callback are objects. Each can be
+set before the element is defined. Neither control renders anything while the core is off,
+and the account popup renders nothing without a person.
+
+**The account popup shows mostly what the product passes**: the name and address from your
+session, your organisations with the role your product gives them there (its own label, already in the
+person's language and shown as given; none, and the row has no second line) and your two actions.
+Identity adds the picture, the colour of the initial, the links to its own account and set up
+screens and the footer, so the popup still signs somebody out while Identity is down. The
+picture is Identity's if the person has one, else yours, else a coloured initial whose tint
+Identity picks from its own id; for somebody with no Identity, pass your own stable user id as
+`id` and the same hash (`avatarTint`) picks it. Set `viaIdentity` once you sign in through
+Identity, and Sign out says it ends both. Sign out leaves this product only.
+
+Every word can be replaced through `labels`; the rest stay English.
+
+### At the bottom of a sidebar, with your own items
+
+```html
+<div style="display: flex; align-items: center">
+  <gp-account layout="row" placement="top" align="start" style="flex: 1"></gp-account>
+  <gp-apps placement="top" align="start"></gp-apps>
+</div>
+```
+
+```ts
+account.labels = { organisations: "Groups" };
+account.items = [
+  { id: "profile", label: "Profile", href: "/settings/profile", icon: userSvg },
+  { id: "account", label: "Account", href: "/settings/account", icon: settingsSvg },
+  { id: "replay", label: "Session recording", onSelect: () => openReplayChoice(), icon: videoSvg },
+];
+```
+
+`layout="row"` draws the trigger as a full width row, the picture with the name over the
+address; `placement="top"` opens both popups upward. Your items follow the organisations
+under your product's name, as links or as buttons; on a link, `onSelect` may call
+`preventDefault()` and navigate with your own router. An icon is SVG markup on a 24 grid and
+is kept to its shapes. Until you sign in through Identity, Sign out is the last row of your
+items' group; with `viaIdentity` it ends both sessions and stands on its own.
+
+### In React
+
+```tsx
+import { GpAccount, GpApps } from "@ghub/identity-chrome/react";
+
+<GpApps core={chrome} />
+<GpAccount core={chrome} product="GAdvisory" person={person} organisations={orgs} onSwitch={switchTo} onSignOut={signOut} />
+```
+
+The wrappers define the elements and set the properties after mounting, so they render on a
+server as the bare tags. React 19 or newer, as an optional peer.
+
+### The host contract
+
+Shadow DOM: nothing reaches in and nothing leaks out but the custom properties a page
+declares on its root, which inherit into the shadow. The controls read the published
+`@ghub/tokens` names, so a page on `@ghub/tokens` is styled with no setup, and Aurora's frosted
+menu where the page is on Aurora:
+
+| Reads                                                                                                                                                                                                | For                                            |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `--ga-menu`, else `--gm-overlay`; `--ga-frost-menu`; `--ga-shadow-menu`, else `--gm-shadow-overlay`                                                                                                  | the picker's surface, its frost and its shadow |
+| `--ga-menu`, else `--gm-sunken`                                                                                                                                                                      | the account popup's tinted ground              |
+| `--ga-track`, else `--gm-overlay`                                                                                                                                                                    | the account popup's panels                     |
+| `--gm-plate`, `--gm-ink`, `--gm-ink-2`, `--gm-ink-3`, `--gm-hairline`, `--gm-control`, `--gm-hover`, `--gm-active`, `--gm-selected`, `--gm-accent`, `--gm-accent-text`, `--gm-ring`, `--gm-crit-ink` | everything else                                |
+| `--font-sans`                                                                                                                                                                                        | the face                                       |
+
+A page that declares none of them gets modern light, or modern dark under
+`prefers-color-scheme: dark`. There is no second accent: the controls take the page's. Both
+follow reduced motion, reduced transparency and forced colours, and below 600 wide each is a
+modal bottom sheet. `part="trigger"` and `part="popup"` are there for placement only.
+
 ## A product's own name and mark
 
 Identity's catalogue is where every product's name and mark live. Read your own from it for

package/dist/core.js

@@ -29,7 +29,7 @@ exports.CACHE_KEY = "gpid.chrome.v1";
 /** A list older than this is not drawn, however the fetch fares. */
 exports.CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 exports.DEFAULT_TIMEOUT_MS = 5000;
-const NO_PERSON = { hasIdentity: false, avatarUrl: null };
+const NO_PERSON = { hasIdentity: false, avatarUrl: null, tint: null };
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -157,7 +157,15 @@ function createChromeCore(options = {}) {
             void publicCall
                 .then((pub) => {
                 if (pub !== null && state.status === "loading" && state.view === null) {
-                    set({ view: { person: NO_PERSON, yours: [], more: pub.more, legal: pub.legal } });
+                    set({
+                        view: {
+                            person: NO_PERSON,
+                            yours: [],
+                            identity: null,
+                            more: pub.more,
+                            legal: pub.legal,
+                        },
+                    });
                 }
             })
                 .catch(() => undefined);
@@ -173,7 +181,7 @@ function createChromeCore(options = {}) {
                 // No personal route configured: the public group is the whole answer.
                 set({
                     status: "ready",
-                    view: { person: NO_PERSON, yours: [], ...publicHalf },
+                    view: { person: NO_PERSON, yours: [], identity: null, ...publicHalf },
                     updatedAt: now(),
                     error: null,
                 });
@@ -186,7 +194,7 @@ function createChromeCore(options = {}) {
             else if (publicHalf !== null) {
                 set({
                     status: "error",
-                    view: { person: NO_PERSON, yours: [], ...publicHalf },
+                    view: { person: NO_PERSON, yours: [], identity: null, ...publicHalf },
                     updatedAt: null,
                     error,
                 });

package/dist/elements/account.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `<gp-account>`, the account popup (GPlatform Identity, sheet 32, option A).
+ *
+ * An avatar at the right end of a product's top bar and, under it, a card on a
+ * tinted ground: who is signed in, where their Identity account is, which
+ * organisation they are acting in, and how to sign out of this product and
+ * only this product (D21).
+ *
+ * **Most of what it shows is the product's.** The name, the address, the
+ * organisations and both actions are properties the product sets from its own
+ * session. Identity adds the picture, the tint, its own two links and the
+ * footer, through the same core as `<gp-apps>`, so the popup still signs
+ * somebody out while Identity cannot be reached.
+ *
+ * **What it is to assistive technology:**
+ *
+ * - The trigger is a `button` with `aria-haspopup="dialog"`, named "Account:
+ *   Mira Kessler", with the same words as a tooltip on hover and on focus after
+ *   half a second, which Escape dismisses without closing anything else (1.4.13).
+ * - The popup is a `dialog` labelled by the person's name and described by their
+ *   address, not modal. Below 600 wide it is a modal sheet with a scrim and a
+ *   contained focus loop, as the picker is.
+ * - Focus opens on the pill (Manage your Identity account, or Set up your
+ *   Identity), else the active organisation, else Sign out. The close button is
+ *   a stop and never the first one.
+ * - The organisations are a `radiogroup`, one tab stop, Up and Down moving
+ *   between them. Choosing is Space or Enter and never an arrow, because
+ *   choosing switches the product: it closes the popup and announces
+ *   "Switched to ...". Five show; "Show all" opens the rest in place, scrolling
+ *   inside, and focus lands on the row that took its place.
+ * - Signing out goes busy in place. A failure keeps the popup open, says in one
+ *   sentence that the person is still signed in, and turns the row into Try
+ *   again. It never claims to have signed out.
+ *
+ * **In a sidebar** (`layout="row"`, `placement="top"`): the trigger is a full
+ * width row, the picture with the name over the address, and the popup opens
+ * upward from it. A product with a sidebar puts `<gp-apps>` at the row's end.
+ *
+ * **The product's own items** (`items`) sit after the organisations, as a group
+ * headed with the product's name. Until the product signs in through Identity,
+ * Sign out is the last row of that same group, because it is one of the
+ * product's own actions; once it does (`viaIdentity`), signing out ends both
+ * sessions and stands on its own again.
+ *
+ * **Hidden for now (D20):** the other accounts and "Add another account" are
+ * not drawn until Identity holds several sessions in one browser and products
+ * sign in through it, and no product can switch them on.
+ *
+ * The words are English by default and every one can be replaced (`labels`).
+ */
+/** Who is signed in, from the product's own session. */
+export interface AccountPerson {
+    name: string;
+    email: string;
+    /** The product's own stable id for this person: it picks the tint where they have no Identity. Never shown. */
+    id?: string;
+    /** The product's own picture, drawn where Identity has none. */
+    avatarUrl?: string | null;
+}
+/** An organisation the person can act in, as the product or Identity passes it (D24, D33). */
+export interface AccountOrganisation {
+    id: string;
+    name: string;
+    /**
+     * The product's own role for this person here, already in the person's
+     * language and shown as given. Roles differ per product and can be custom,
+     * so the element has no list of its own. None, and the row has no second line.
+     */
+    role?: string | null;
+    active: boolean;
+}
+/** One of the product's own items in the popup, such as its profile or its settings. */
+export interface AccountItem {
+    /** Stable across renders, so focus stays on the item when the list is set again. */
+    id: string;
+    label: string;
+    /** A link, so middle click and opening in a new tab work as on any link. Relative to the page. */
+    href?: string;
+    /**
+     * Called when it is chosen. On a link, `event.preventDefault()` hands the
+     * navigation to the product, such as a client side router.
+     */
+    onSelect?: (event: MouseEvent) => void;
+    /** SVG markup on a 24 grid, drawn at 18 in the row's ink. Only shapes are kept. */
+    icon?: string;
+}
+/** Signs the person out of this product. Rejecting means they are still signed in. */
+export type SignOutHandler = () => unknown;
+/** Switches the product to this organisation. Rejecting means it did not. */
+export type SwitchHandler = (organisationId: string) => unknown;
+export interface AccountLabels {
+    /** The trigger's name and its tooltip. */
+    trigger: (name: string) => string;
+    signedInTo: (product: string) => string;
+    close: string;
+    changePicture: string;
+    manage: string;
+    setUp: string;
+    organisations: string;
+    active: string;
+    showAll: (count: number) => string;
+    switched: (organisation: string) => string;
+    switchFailed: (organisation: string) => string;
+    signOut: (product: string) => string;
+    /** In a product that signs in through Identity, where signing out ends both. */
+    signOutBoth: (product: string) => string;
+    signingOut: (product: string) => string;
+    signOutFailed: (product: string) => string;
+    retry: string;
+    /** Stands in for the product's name where it was not given. */
+    thisProduct: string;
+    terms: string;
+    privacy: string;
+}
+export declare const ACCOUNT_LABELS: AccountLabels;
+export declare const ACCOUNT_CSS: string;
+/**
+ * A product's icon, kept to shapes: no script, no link, no style and no reference
+ * to anything outside it, because it is drawn inside every page the element is on.
+ */
+export declare function iconOf(markup: string): SVGSVGElement | null;
+/**
+ * Defines `<gp-account>` once, where custom elements exist. Safe to import on a
+ * server: nothing touches the DOM until this is called in a browser.
+ */
+export declare function defineAccountElement(name?: string): void;
+/** The class itself, for a caller that registers it under its own name or in a scoped registry. */
+export declare function createAccountElementClass(): CustomElementConstructor;
+//# sourceMappingURL=account.d.ts.map