@plone-collective/volto-identity 1.0.0-alpha.1

package/src/storybook/withPage.test.tsx

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { render } from '../testing';
+import { MemoryRouter } from 'react-router-dom';
+import { CookiesProvider } from 'react-cookie';
+import { Provider } from 'react-redux';
+import React from 'react';
+
+import { ensureToolbarHost, PAGE_WIDTH } from './withPage';
+import { VOLTO_CHROME } from '../stories/fixtures';
+import Identities from '../components/Identities/Identities';
+
+/**
+ * What the story environment has to be able to do.
+ *
+ * Five pages here portal Volto's `Toolbar` into `#toolbar` and are wrapped in
+ * `withCookies`. Every other test of those pages stubs the toolbar out, which
+ * is right for a unit test and means nothing here would notice the *stories*
+ * being unrenderable -- which they were, for both reasons at once.
+ *
+ * So this renders one of them for real, through the same helper the decorator
+ * uses and the same provider it supplies. It is a test of the story
+ * environment, not of the page.
+ */
+
+const LOADED = { loading: false, loaded: true, error: null };
+
+function storyState() {
+  return {
+    identities: { ...LOADED, data: [] },
+    linkableProviders: { ...LOADED, data: [] },
+    loginProviders: { ...LOADED, data: [] },
+    myProfile: {
+      ...LOADED,
+      data: { profile: '/identity-profiles/erico', emails: [] },
+    },
+    identityLinking: {},
+    identityUnlink: {},
+    preferredEmail: {},
+    ...VOLTO_CHROME,
+  };
+}
+
+describe('the story page environment', () => {
+  afterEach(() => {
+    document.getElementById('toolbar')?.remove();
+  });
+
+  it('gives the toolbar somewhere to go', () => {
+    ensureToolbarHost();
+
+    expect(document.getElementById('toolbar')).toBeTruthy();
+  });
+
+  it('makes only one, however often it is asked', () => {
+    ensureToolbarHost();
+    ensureToolbarHost();
+
+    expect(document.querySelectorAll('#toolbar')).toHaveLength(1);
+  });
+
+  it('renders a page that portals its toolbar', () => {
+    // Without the host this threw "Target container is not a DOM element";
+    // without the provider, "Cannot read properties of null (reading
+    // 'getAll')" out of react-cookie. Both were the whole story failing to
+    // render, and neither was visible from the page's own tests.
+    ensureToolbarHost();
+    const state = storyState();
+    const store = {
+      getState: () => state,
+      dispatch: (action: unknown) => action,
+      subscribe: () => () => {},
+    };
+
+    render(
+      <CookiesProvider>
+        <Provider store={store as never}>
+          <MemoryRouter initialEntries={['/identities']}>
+            <Identities />
+          </MemoryRouter>
+        </Provider>
+      </CookiesProvider>,
+    );
+
+    expect(document.querySelector('#page-identities')).toBeTruthy();
+  });
+
+  it('has a measure to constrain a story to', () => {
+    expect(PAGE_WIDTH).toMatch(/^\d+px$/);
+  });
+});

package/src/storybook/withPage.tsx

@@ -0,0 +1,110 @@
+/**
+ * The page context a story does not otherwise get.
+ *
+ * Modelled on `volto-light-theme`'s `withTheme`: one global decorator that
+ * puts every story in the surroundings its component has on a real page,
+ * rather than each story reinventing them. Three things a bare story lacks.
+ *
+ * 1. **Somewhere for the toolbar to go.** Five pages here portal Volto's
+ *    `Toolbar` into `#toolbar`, an element Volto's app shell renders and
+ *    Storybook does not. `createPortal` is called during render and throws on
+ *    a null container, so those stories did not render at all -- which is what
+ *    "the Identities story is broken" was.
+ *
+ * 2. **A cookie provider.** Volto's `Toolbar` is wrapped in `withCookies`, and
+ *    without a provider above it `react-cookie` throws reading a jar that is
+ *    not there. `start-client.jsx` wraps the whole app in one, so this is the
+ *    real shell rather than a prop for the stories' benefit.
+ *
+ * 3. **A measure.** On the canvas a story stretches to the viewport, so a
+ *    panel meant to be read at a page's width was seen at twice it. This
+ *    constrains and centres, the way the theme's decorator does.
+ *
+ * A story that is genuinely full-bleed -- or that supplies its own container,
+ * as everything inside `LoginPanel` does -- opts out with
+ * `parameters: { fullBleed: true }`.
+ * @module storybook/withPage
+ */
+import React from 'react';
+import type { Decorator } from '@storybook/react';
+import { CookiesProvider } from 'react-cookie';
+
+/**
+ * The width these pages are read at.
+ *
+ * Deliberately not a restatement of Semantic UI's container width: that is
+ * computed from breakpoints and gutters rather than written down as a number,
+ * so quoting one here would be an invention that looked like a fact. The
+ * pages that use a `Container` still constrain themselves inside this; what
+ * this is for is the panels and lists that do not, which were edge-to-edge.
+ */
+export const PAGE_WIDTH = '1000px';
+
+/**
+ * Make sure `#toolbar` exists before any story renders into it.
+ *
+ * At module scope rather than in an effect: `createPortal` reads the element
+ * during the story's *render*, which happens before any effect of a decorator
+ * above it has run. Appended to `document.body`, which is where Volto's app
+ * shell puts it and what its fixed positioning expects.
+ *
+ * There can only be one, because Volto's toolbar finds it by
+ * `getElementById`. `withUserMenu` therefore renders *into* this element
+ * rather than making a second one -- the menu styles need `#toolbar` as an
+ * ancestor, and a duplicate id would shadow this for the pages that portal
+ * their toolbar here.
+ *
+ * @returns The host, or null where there is no document.
+ */
+export function ensureToolbarHost(): HTMLElement | null {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+  const existing = document.getElementById('toolbar');
+  if (existing) {
+    return existing;
+  }
+  const host = document.createElement('div');
+  host.id = 'toolbar';
+  document.body.appendChild(host);
+  return host;
+}
+
+ensureToolbarHost();
+
+/**
+ * Constrain and centre a story, unless it brings its own container.
+ *
+ * @param fullBleed Whether the story fills whatever it is given.
+ * @param children The story.
+ * @returns The wrapper, or the story unchanged.
+ */
+const PageShell: React.FC<{
+  fullBleed: boolean;
+  children: React.ReactNode;
+}> = ({ fullBleed, children }) => {
+  if (fullBleed) {
+    return <>{children}</>;
+  }
+  return (
+    <div
+      style={{
+        maxWidth: PAGE_WIDTH,
+        padding: '1rem',
+        margin: '0 auto',
+      }}
+    >
+      {children}
+    </div>
+  );
+};
+
+export const withPage: Decorator = (Story, context) => (
+  <CookiesProvider>
+    <PageShell fullBleed={Boolean(context.parameters?.fullBleed)}>
+      <Story />
+    </PageShell>
+  </CookiesProvider>
+);
+
+export default withPage;

package/src/storybook/withUserMenu.test.tsx

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { render } from '../testing';
+import React from 'react';
+
+import {
+  withMenuList,
+  withPersonalTools,
+  withToolbar,
+  withToolbarButton,
+} from './withUserMenu';
+
+/**
+ * That the menu markup lands where its stylesheet can reach it.
+ *
+ * Every rule for `.pastanaga-menu`, `.pastanaga-menu-list` and `.toolbar` is
+ * nested under `#toolbar` in Volto's `toolbar.less`, so the class names alone
+ * style nothing. A story with the classes and no ancestor renders an
+ * unstyled column of links and looks like a broken component -- which is what
+ * these decorators exist to stop, and what nothing else here would notice.
+ *
+ * There must also be exactly one `#toolbar`: Volto's pages find it with
+ * `getElementById` to portal their own toolbar into.
+ */
+
+/** A story, as Storybook hands one to a decorator. */
+const story = () => <a href="/identities">Sign-in methods</a>;
+const context = {} as never;
+
+describe('the user-menu decorators', () => {
+  afterEach(() => {
+    document.getElementById('toolbar')?.remove();
+  });
+
+  it('puts the panel inside #toolbar', () => {
+    render(<>{withPersonalTools(story, context)}</>);
+
+    const panel = document.querySelector('.personal-tools.pastanaga-menu');
+    expect(panel).toBeTruthy();
+    expect(panel?.closest('#toolbar')).toBeTruthy();
+  });
+
+  it('puts the list where the panel styles it', () => {
+    render(
+      <>{withPersonalTools(() => withMenuList(story, context), context)}</>,
+    );
+
+    const entry = document.querySelector('#toolbar .pastanaga-menu-list ul a');
+    expect(entry).toBeTruthy();
+  });
+
+  it('puts the avatar on the toolbar button, inside #toolbar', () => {
+    render(<>{withToolbarButton(story, context)}</>);
+
+    const button = document.querySelector('button#toolbar-personal.user');
+    expect(button).toBeTruthy();
+    expect(button?.closest('#toolbar .toolbar')).toBeTruthy();
+  });
+
+  it('gives a component that brings its own markup just the ancestor', () => {
+    render(<>{withToolbar(story, context)}</>);
+
+    expect(document.querySelector('#toolbar a')).toBeTruthy();
+    expect(document.querySelector('#toolbar .pastanaga-menu')).toBeNull();
+  });
+
+  it('never makes a second #toolbar', () => {
+    // A duplicate earlier in the document would shadow the host that pages
+    // portal their toolbar into, and `getElementById` would hand them this.
+    render(
+      <>
+        {withPersonalTools(story, context)}
+        {withToolbarButton(story, context)}
+      </>,
+    );
+
+    expect(document.querySelectorAll('#toolbar')).toHaveLength(1);
+  });
+});

package/src/storybook/withUserMenu.tsx

@@ -0,0 +1,136 @@
+/**
+ * The two places this add-on puts something in Volto's toolbar.
+ *
+ * Both are markup the components land *inside* rather than markup they
+ * render, and the whole of Volto's toolbar stylesheet is nested under an id:
+ *
+ * ```less
+ * #toolbar {
+ *   .toolbar { … }
+ *   .pastanaga-menu { width: 100vw; height: calc(100vh - 100px); … }
+ *   .pastanaga-menu-list { … }
+ * }
+ * ```
+ *
+ * So `#toolbar` is not decoration -- without that ancestor **none** of these
+ * rules match, and a story showing the right class names still shows an
+ * unstyled list. That is what made the menu stories look wrong, and it is why
+ * `PersonalTools`, which renders `.personal-tools.pastanaga-menu` itself,
+ * looked wrong even though it carries the markup already.
+ *
+ * There can be only one `#toolbar`: Volto's pages find it with
+ * `getElementById` to portal their toolbar into, and a second one earlier in
+ * the document would shadow it. So these decorators render *into* the one
+ * `withPage` guarantees rather than making their own -- which is also what
+ * happens on a real site, where the menu is a child of the toolbar it slides
+ * over.
+ *
+ * The nesting, read out of `PersonalTools.jsx` and this package's
+ * `Toolbar.jsx`:
+ *
+ * ```
+ * <div id="toolbar">                              <- withToolbar
+ *   <div class="personal-tools pastanaga-menu">   <- withPersonalTools
+ *     <header class="header">…</header>
+ *     <div class="pastanaga-menu-list">
+ *       <ul>…entries…</ul>                        <- withMenuList
+ *
+ *   <div class="toolbar">                         <- withToolbarButton
+ *     …<button class="user" id="toolbar-personal">…avatar…
+ * ```
+ * @module storybook/withUserMenu
+ */
+import React from 'react';
+import { createPortal } from 'react-dom';
+import type { Decorator } from '@storybook/react';
+import { MemoryRouter } from 'react-router-dom';
+
+import { ensureToolbarHost } from './withPage';
+
+/**
+ * Render children inside the one `#toolbar` there is.
+ *
+ * A portal rather than a wrapper element, so nothing has to invent a second
+ * element with that id. What is rendered still belongs to the story's React
+ * tree -- context, the router and the store all reach it -- and appears in
+ * the preview's own document, so the canvas shows it.
+ */
+const InToolbar: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const host = ensureToolbarHost();
+  return host ? createPortal(children, host) : null;
+};
+
+/**
+ * The `#toolbar` ancestor every rule in `toolbar.less` is nested under.
+ *
+ * For a component that already renders its own toolbar markup -- the
+ * shadowed `PersonalTools` is the whole of that -- and the base the two
+ * decorators below build on.
+ */
+export const withToolbar: Decorator = (Story) => (
+  <MemoryRouter>
+    <InToolbar>
+      <Story />
+    </InToolbar>
+  </MemoryRouter>
+);
+
+/**
+ * The personal-tools panel, down to the list its entries sit in.
+ *
+ * Stops short of the `<ul>` because the plug stories have to put it inside
+ * their `PluggablesProvider` -- a plug and the pluggable that consumes it
+ * must share one provider, and the pluggable is what renders the entries.
+ * `PluggablesProvider` contributes no DOM, so the nesting Volto's stylesheet
+ * keys on comes out the same either way.
+ */
+export const withPersonalTools: Decorator = (Story) => (
+  <MemoryRouter>
+    <InToolbar>
+      <div className="personal-tools pastanaga-menu">
+        <div className="pastanaga-menu-list">
+          <Story />
+        </div>
+      </div>
+    </InToolbar>
+  </MemoryRouter>
+);
+
+/**
+ * The list itself, for a story that renders one entry rather than a plug.
+ *
+ * Compose it inside `withPersonalTools`: Storybook applies the first
+ * decorator innermost, so `[withMenuList, withPersonalTools]` reads in the
+ * order the DOM nests.
+ */
+export const withMenuList: Decorator = (Story) => (
+  <ul>
+    <Story />
+  </ul>
+);
+
+/**
+ * The toolbar button the avatar is drawn on.
+ *
+ * `#toolbar-personal` is the button this add-on's `Toolbar.jsx` replaces
+ * Volto's camera icon in, so this is where the avatar is actually seen --
+ * 30px, on the toolbar's own ground, rather than floating on the canvas.
+ * `expanded` because the toolbar is 20px tall until it is.
+ */
+export const withToolbarButton: Decorator = (Story) => (
+  <MemoryRouter>
+    <InToolbar>
+      <div className="toolbar expanded">
+        <div className="toolbar-body">
+          <div className="toolbar-actions">
+            <div className="toolbar-bottom">
+              <button className="user" id="toolbar-personal" type="button">
+                <Story />
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </InToolbar>
+  </MemoryRouter>
+);

package/src/styles.css

@@ -0,0 +1,262 @@
+/**
+ * The root stylesheet for volto-identity.
+ *
+ * Two things live here and nothing else: the design tokens every component
+ * reads, and the handful of base classes more than one component wears.
+ * Everything that styles one component lives next to it, in a `.scss` that
+ * component imports itself -- the shape `volto-authomatic` uses, so a rule is
+ * found by opening the file whose markup it styles rather than by scrolling
+ * one long stylesheet.
+ *
+ * The tokens are deliberately few, and structural: layout, spacing and the
+ * state colours a user has to be able to tell apart. Typography and form
+ * controls inherit from whatever theme the site runs, so the add-on looks
+ * like part of the site rather than like itself.
+ */
+
+:root {
+  /* Rhythm ---------------------------------------------------------------- */
+  --identity-gap: 12px;
+  --identity-radius: 4px;
+  --identity-border: 1px solid rgba(0, 0, 0, 0.15);
+
+  /* Palette. The accent and the danger colour are volto-authomatic's, so a
+     user who has seen one of these login pages recognises the other. */
+  --identity-accent: #007eb1;
+  --identity-danger: #ee0000;
+  --identity-muted: rgba(0, 0, 0, 0.6);
+  --identity-error: #a01c1c;
+  --identity-ok: #1c7a3e;
+
+  /* Surfaces: the card the login form sits in, and the panels the control
+     panel and the identities page are built from. */
+  /* Form fields. `@plone/components`' TextField.css draws its border with
+     `var(--border-color)`, which is defined in that package's theme.css -- a
+     stylesheet this add-on never loads, since it imports the widget's CSS on
+     its own. The custom property is therefore undefined, the `border`
+     shorthand is invalid at computed-value time, and what should have been a
+     grey underline resolved to no border at all. So the fields declare their
+     own. */
+  --identity-field-border: rgba(0, 0, 0, 0.3);
+
+  --identity-surface-bg: #fff;
+  --identity-surface-border: #c7d5d8;
+  --identity-surface-header-bg: #edf1f2;
+  --identity-surface-shadow: 0 2px 4px 0 rgba(34, 36, 38, 0.12),
+    0 2px 10px 0 rgba(34, 36, 38, 0.15);
+
+  /* The login card, sized the way Volto's own login page is. */
+  --identity-login-width: 350px;
+
+  /* The card's body never gets shorter than this. Every state of the login
+     page occupies it -- the picker, either form, a wait, a refusal -- and
+     without a floor the card resized on each of them, which read as the page
+     jumping about rather than as one card changing what it says. */
+  --identity-login-min-height: 260px;
+
+  /* What a wait or a refusal is drawn on: the card's own grey, near enough
+     opaque. Not white, which read as a hole in the card rather than as
+     something over it; and not transparent enough to leave the buttons
+     underneath looking pressable while they are not. */
+  --identity-overlay-veil: rgba(237, 241, 242, 0.96);
+
+  /* Provider buttons: geometry and per-provider colours, also from
+     volto-authomatic. */
+  --identity-provider-width: 300px;
+  --identity-provider-height: 45px;
+  --identity-provider-radius: 3px;
+  --identity-provider-shadow: rgba(0, 0, 0, 0.5) 0 1px 2px;
+
+  --identity-provider-default-bg: #000;
+  --identity-provider-default-color: #fff;
+
+  --identity-provider-github-bg: #333;
+  --identity-provider-github-bg-hover: #555;
+  --identity-provider-github-color: #fff;
+
+  --identity-provider-google-bg: #fff;
+  --identity-provider-google-bg-hover: #eff0ee;
+  --identity-provider-google-color: #000;
+
+  /* The local password form is offered as one of these. The colours are
+     volto-authomatic's `plone` provider, so the button a visitor presses to
+     sign in with a site account looks the same in both add-ons. */
+  --identity-provider-plone-bg: #0083be;
+  --identity-provider-plone-bg-hover: #006c9e;
+  --identity-provider-plone-color: #fff;
+
+  --identity-provider-oidc-bg: #333;
+  --identity-provider-oidc-bg-hover: #555;
+  --identity-provider-oidc-color: #fff;
+}
+
+/* Base classes ------------------------------------------------------------
+ *
+ * Worn explicitly by the markup. They used to be selector lists naming every
+ * component that wanted the look, which meant a new component silently got
+ * none of it until somebody remembered to extend the list.
+ */
+
+/** A bordered, shadowed card: the login panel and each control-panel section. */
+.identity-surface {
+  border: 1px solid var(--identity-surface-border);
+  background: var(--identity-surface-bg);
+  box-shadow: var(--identity-surface-shadow);
+}
+
+/** Its titled header strip. */
+.identity-surface__header {
+  padding: 12px 16px;
+  border-bottom: 0.22222222rem solid var(--identity-surface-border);
+  margin: 0;
+  font-size: 16px;
+  font-weight: 500;
+}
+
+/** Every button this add-on renders itself, rather than through Volto. */
+.identity-button {
+  padding: 8px 14px;
+  border: 1px solid var(--identity-accent);
+  border-radius: var(--identity-radius);
+  background: transparent;
+  color: var(--identity-accent);
+  cursor: pointer;
+  font-size: 14px;
+}
+
+.identity-button:hover:not(:disabled) {
+  background: var(--identity-surface-header-bg);
+}
+
+.identity-button:disabled {
+  border-color: var(--identity-muted);
+  color: var(--identity-muted);
+  cursor: default;
+  opacity: 0.6;
+}
+
+/** The affirmative one, where a screen asks a yes-or-no question. */
+.identity-button--primary {
+  background: var(--identity-accent);
+  color: var(--identity-surface-bg);
+}
+
+.identity-button--primary:hover:not(:disabled) {
+  background: var(--identity-accent);
+  opacity: 0.9;
+}
+
+/** The irreversible ones say so. */
+.identity-button--danger {
+  border-color: var(--identity-danger);
+  color: var(--identity-danger);
+}
+
+/** A refusal, wherever it is reported. */
+.identity-error {
+  margin: 0;
+  color: var(--identity-error);
+}
+
+/** Secondary text: an empty state, or what a control costs. */
+.identity-note {
+  color: var(--identity-muted);
+  font-size: 0.9em;
+}
+
+/**
+ * A page split into sections a reader picks between.
+ *
+ * Worn by the `Tabs` from `@plone/components`, whose own `Tabs.css` each page
+ * imports beside this -- the same split the fields use, and for the same
+ * reason written at `--identity-field-border` above. This adds only what
+ * makes the tabs look like the rest of the add-on: the surface's border under
+ * the strip, and the accent under whichever tab is current.
+ *
+ * Two pages wear it -- a user's account in the control panel, and the
+ * sign-in methods page a person manages their own with. They are the same
+ * question asked by an administrator and by the account's owner, so they are
+ * the same design, described once.
+ */
+.identity-tabs .react-aria-TabList {
+  display: flex;
+  flex-direction: row;
+  border-bottom: 1px solid var(--identity-surface-border);
+  gap: 4px;
+}
+
+.identity-tabs .react-aria-Tab {
+  padding: 10px 16px;
+  border-bottom: 3px solid transparent;
+  margin-bottom: -1px;
+  color: var(--identity-muted);
+  cursor: pointer;
+  font-size: 14px;
+  font-weight: 500;
+  outline: none;
+}
+
+.identity-tabs .react-aria-Tab[data-hovered] {
+  color: var(--identity-accent);
+}
+
+.identity-tabs .react-aria-Tab[data-selected] {
+  border-bottom-color: var(--identity-accent);
+  color: var(--identity-accent);
+}
+
+/* Keyboard focus has to be visible even on the tab already selected, where
+   the accent underline says nothing about where focus is. */
+.identity-tabs .react-aria-Tab[data-focus-visible] {
+  outline: 2px solid var(--identity-accent);
+  outline-offset: -2px;
+}
+
+.identity-tabs .react-aria-Tab[data-disabled] {
+  color: var(--identity-muted);
+  cursor: default;
+  opacity: 0.5;
+}
+
+.identity-tabs .react-aria-TabPanel {
+  padding-top: var(--identity-gap);
+  outline: none;
+}
+
+/**
+ * A wait, drawn rather than described.
+ *
+ * Its own rule rather than `@plone/components`' `Spinner` for the reason the
+ * field border above is: that package ships its components and its CSS
+ * separately, and this add-on loads a stylesheet per widget it uses. A
+ * spinner is a border and a rotation, which is less than the note explaining
+ * why the imported one came through unstyled.
+ *
+ * Decorative: whatever is waiting says so in text beside this, and that text
+ * is what a screen reader should reach.
+ */
+.identity-spinner {
+  display: inline-block;
+  width: 1.15em;
+  height: 1.15em;
+  flex: none;
+  border: 2px solid var(--identity-surface-border);
+  border-radius: 50%;
+  border-top-color: var(--identity-accent);
+  animation: identity-spin 0.7s linear infinite;
+}
+
+@keyframes identity-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* A spin that cannot be stopped is a spin somebody has to look away from. */
+@media (prefers-reduced-motion: reduce) {
+  .identity-spinner {
+    border-top-color: var(--identity-accent);
+    animation: none;
+    opacity: 0.6;
+  }
+}