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

package/src/components/UserMenu/ProfileMenuItem.tsx

@@ -0,0 +1,60 @@
+/**
+ * A link to the user's own Profile, plugged into Volto's user menu.
+ *
+ * Only for a user who has one -- which, as :mod:`helpers/profileSource`
+ * explains, is the same thing as their fields being held in it.
+ *
+ * For that user it *replaces* Volto's own Profile link rather than sitting
+ * beside it, and takes its name: two entries both called "Profile" make the
+ * reader guess which is which, and the content object is where their fields
+ * actually live. Taking the slot rather than adding to it is why they share
+ * an `order`, and why
+ * :func:`~components/UserMenu/UserMenuPlugs.PersonalInformationMenuItem`
+ * renders nothing once this one can.
+ * @module components/UserMenu/ProfileMenuItem
+ */
+import React from 'react';
+import { useSelector } from 'react-redux';
+import { defineMessages, useIntl } from 'react-intl';
+import { Plug } from '@plone/volto/components/manage/Pluggable';
+import { flattenToAppURL } from '@plone/volto/helpers/Url/Url';
+
+import { profileHoldsTheFields } from '../../helpers/profileSource';
+import MenuItem from './MenuItem';
+
+const messages = defineMessages({
+  // The same label Volto's own entry carries, because this stands in its
+  // place rather than beside it.
+  title: { id: 'Profile', defaultMessage: 'Profile' },
+});
+
+const ProfileMenuItem: React.FC = () => {
+  const intl = useIntl();
+  // A primitive, not the user object: `useSelector` compares by identity,
+  // and selecting the user whole re-renders this on every store
+  // notification.
+  const profileUrl = useSelector(
+    (state: any) => state.userProfile?.data?.profile_url,
+  );
+
+  if (!profileHoldsTheFields(profileUrl)) {
+    return null;
+  }
+
+  return (
+    <Plug
+      pluggable="toolbar-user-menu"
+      id="identity-profile"
+      order={10}
+      dependencies={[profileUrl]}
+    >
+      <MenuItem
+        id="toolbar-identity-profile"
+        label={intl.formatMessage(messages.title)}
+        to={flattenToAppURL(profileUrl)}
+      />
+    </Plug>
+  );
+};
+
+export default ProfileMenuItem;

package/src/components/UserMenu/UserAvatar.scss

@@ -0,0 +1,23 @@
+.identity-avatar {
+  display: inline-flex;
+  overflow: hidden;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  vertical-align: middle;
+}
+
+.identity-avatar--picture {
+  object-fit: cover;
+}
+
+.identity-avatar--initials {
+  color: #fff;
+  font-weight: 600;
+  // The initials are drawn, not read as text: selecting them out of a
+  // toolbar button is never what somebody meant to do.
+  letter-spacing: 0.02em;
+  line-height: 1;
+  user-select: none;
+}

package/src/components/UserMenu/UserAvatar.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Provider } from 'react-redux';
+import React from 'react';
+
+import UserAvatar from './UserAvatar';
+import { LOADED, PORTRAIT, USER, withUser } from '../../stories/fixtures';
+import { withToolbarButton } from '../../storybook/withUserMenu';
+
+const meta: Meta<typeof UserAvatar> = {
+  title: 'Identity/UserMenu/UserAvatar',
+  component: UserAvatar,
+};
+export default meta;
+
+type Story = StoryObj<typeof UserAvatar>;
+
+/**
+ * Where it is actually seen.
+ *
+ * This add-on's `Toolbar.jsx` puts it on `#toolbar-personal` in place of
+ * Volto's camera icon, at 30px on the toolbar's own ground. The stories below
+ * show the component; this one shows the component in its place, which is the
+ * only one that says whether 30px is enough to tell two people apart.
+ */
+export const OnTheToolbarButton: Story = {
+  args: { size: '30px' },
+  decorators: [withUser({ portrait: null }), withToolbarButton],
+  // The toolbar is fixed and full width; boxing it in the page wrapper would
+  // show it somewhere it never is.
+  parameters: { fullBleed: true },
+};
+
+/** The user uploaded a portrait, so it is the portrait. */
+export const WithPortrait: Story = {
+  decorators: [withUser({ portrait: PORTRAIT })],
+};
+
+/**
+ * The common case. Most people never upload a portrait, and Volto drew a
+ * camera icon for all of them -- the same picture for everybody.
+ */
+export const Initials: Story = {
+  decorators: [withUser({ portrait: null })],
+};
+
+/**
+ * Several people at once, which is the only way to see the point of the
+ * colour: it is derived from the userid, so the same person is the same
+ * colour everywhere and two people in a list are told apart at a glance.
+ *
+ * Each avatar gets its own store, because the user is read from it rather
+ * than passed in as a prop.
+ */
+export const DifferentPeople: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '0.5rem' }}>
+      {[
+        { id: 'alice', fullname: 'Alice Liddell' },
+        { id: 'bob', fullname: 'Bob Ross' },
+        { id: 'carol', fullname: 'Carol Danvers' },
+        { id: 'dave', fullname: 'Dave Grohl' },
+        { id: 'ericof', fullname: 'Érico Andrei' },
+      ].map((who) => (
+        <Provider
+          key={who.id}
+          store={
+            {
+              getState: () => ({
+                userProfile: { ...LOADED, data: { ...USER, ...who } },
+              }),
+              dispatch: (action: unknown) => action,
+              subscribe: () => () => {},
+            } as never
+          }
+        >
+          <UserAvatar size="48px" />
+        </Provider>
+      ))}
+    </div>
+  ),
+};
+
+/** A middle name must not push the surname out: this is ÉA, not ÉD. */
+export const MiddleName: Story = {
+  decorators: [withUser({ id: 'ericof', fullname: 'Érico de Andrei' })],
+};
+
+/** One word is the only case that takes two letters from the same word. */
+export const SingleName: Story = {
+  decorators: [withUser({ id: 'madonna', fullname: 'Madonna' })],
+};
+
+/** No name yet: the userid stands in rather than leaving an empty circle. */
+export const NameNotLoadedYet: Story = {
+  decorators: [withUser({ id: 'alice', fullname: null })],
+};
+
+/**
+ * An anonymous visitor. The component mounts on every route, so this is a
+ * state it really renders in, not a hypothetical.
+ */
+export const Anonymous: Story = {
+  decorators: [withUser(null)],
+};
+
+/** The size the toolbar button asks for, beside the size the menu used to. */
+export const Large: Story = {
+  args: { size: '96px' },
+  decorators: [withUser({ portrait: null })],
+};
+
+/**
+ * A portrait URL that does not resolve falls back to the initials.
+ *
+ * A deleted portrait, or a stale URL after a rename. The browser's
+ * broken-image glyph reads as a bug in the site rather than as a missing
+ * photograph, which is what this avoids.
+ */
+export const BrokenPortrait: Story = {
+  decorators: [withUser({ portrait: '/no-such-portrait.png' })],
+};

package/src/components/UserMenu/UserAvatar.test.tsx

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest';
+import { fireEvent, render, screen } from '../../testing';
+import { Provider } from 'react-redux';
+import React from 'react';
+
+import UserAvatar from './UserAvatar';
+import { AVATAR_COLORS } from '../../helpers/avatar';
+
+function renderAvatar(data: unknown, props = {}) {
+  const store = {
+    getState: () => ({
+      userProfile: { loading: false, loaded: true, error: null, data },
+    }),
+    dispatch: (action: unknown) => action,
+    subscribe: () => () => {},
+  };
+  return render(
+    <Provider store={store as never}>
+      <UserAvatar {...props} />
+    </Provider>,
+  );
+}
+
+describe('UserAvatar', () => {
+  it('renders the portrait when the user has one', () => {
+    renderAvatar({
+      id: 'alice',
+      fullname: 'Alice Liddell',
+      portrait: 'http://localhost:8080/Plone/portrait.png',
+    });
+
+    const img = screen.getByRole('img', { name: /user avatar/i });
+
+    // Flattened: the store holds the backend URL and the browser has to ask
+    // this site for it.
+    expect(img.getAttribute('src')).toBe('/portrait.png');
+  });
+
+  it('falls back to initials on a colour', () => {
+    // Volto draws a camera icon here, which is the same picture for every
+    // user without a portrait.
+    const { container } = renderAvatar({
+      id: 'alice',
+      fullname: 'Alice Liddell',
+    });
+
+    const avatar = container.querySelector('.identity-avatar--initials');
+    expect(avatar?.textContent).toBe('AL');
+    expect(avatar).toBeTruthy();
+  });
+
+  it('colours the initials from the palette', () => {
+    const { container } = renderAvatar({
+      id: 'alice',
+      fullname: 'Alice Liddell',
+    });
+
+    const style = container
+      .querySelector('.identity-avatar--initials')
+      ?.getAttribute('style');
+
+    // jsdom renders the hex as rgb(), so assert on the palette having been
+    // consulted rather than on one exact string.
+    expect(style).toContain('background-color');
+    expect(AVATAR_COLORS.length).toBeGreaterThan(0);
+  });
+
+  it('falls back to the userid when there is no name yet', () => {
+    const { container } = renderAvatar({ id: 'alice' });
+
+    expect(
+      container.querySelector('.identity-avatar--initials')?.textContent,
+    ).toBe('AL');
+  });
+
+  it('renders a plain circle for an anonymous visitor', () => {
+    // Mounted on every route, so this is the common case, not an edge one.
+    const { container } = renderAvatar(null);
+
+    const avatar = container.querySelector('.identity-avatar--initials');
+    expect(avatar?.textContent).toBe('');
+    // Nothing to read: announcing an empty circle as "user avatar" is noise.
+    expect(avatar?.getAttribute('aria-hidden')).toBe('true');
+    expect(avatar?.getAttribute('role')).toBeNull();
+  });
+
+  it('falls back to initials when the portrait fails to load', () => {
+    // A deleted portrait, or a stale URL after a rename. The browser's
+    // broken-image glyph reads as a bug in the site rather than as a
+    // missing photograph.
+    const { container } = renderAvatar({
+      id: 'alice',
+      fullname: 'Alice Liddell',
+      portrait: '/gone.png',
+    });
+
+    fireEvent.error(screen.getByRole('img', { name: /user avatar/i }));
+
+    expect(container.querySelector('img')).toBeNull();
+    expect(
+      container.querySelector('.identity-avatar--initials')?.textContent,
+    ).toBe('AL');
+  });
+
+  it('accepts extra classes without losing its own', () => {
+    const { container } = renderAvatar({ id: 'alice' }, { className: 'mine' });
+
+    const avatar = container.querySelector('.identity-avatar');
+    expect(avatar?.className).toContain('identity-avatar--initials');
+    expect(avatar?.className).toContain('mine');
+  });
+
+  it('takes the size it is given', () => {
+    const { container } = renderAvatar({ id: 'alice' }, { size: '96px' });
+
+    expect(
+      container.querySelector('.identity-avatar')?.getAttribute('style'),
+    ).toContain('96px');
+  });
+});

package/src/components/UserMenu/UserAvatar.tsx

@@ -0,0 +1,119 @@
+/**
+ * The signed-in user, as a picture or as their initials.
+ *
+ * Reads the user this package keeps in the store rather than Volto's
+ * `state.users.user`: that one is fetched when the personal-tools menu opens
+ * and cleared around it, and this renders in the toolbar, on every page,
+ * whether or not the menu was ever opened.
+ *
+ * It always renders *something*. A user with no portrait gets initials on a
+ * colour derived from their userid; a portrait that fails to load falls back
+ * to those initials rather than to a broken-image glyph; a user whose name
+ * has not arrived gets the plain circle, which is what the space looked like
+ * before.
+ * @module components/UserMenu/UserAvatar
+ */
+import React, { useMemo, useState } from 'react';
+import { useSelector } from 'react-redux';
+import { useIntl, defineMessages } from 'react-intl';
+import { flattenToAppURL } from '@plone/volto/helpers/Url/Url';
+
+import { colorFor, initialsFor } from '../../helpers/avatar';
+
+import './UserAvatar.scss';
+
+const messages = defineMessages({
+  avatar: { id: 'user avatar', defaultMessage: 'user avatar' },
+});
+
+export interface UserAvatarProps {
+  /** Rendered size, as a CSS length. Square. */
+  size?: string;
+  /** Extra classes, for a caller that places the avatar itself. */
+  className?: string;
+}
+
+/**
+ * Join the class names for one variant.
+ *
+ * Deliberately not `classnames`: that is Volto's dependency, not this
+ * package's, and this add-on declares no runtime dependencies at all. One
+ * `filter` is a smaller price than the first entry in that list.
+ *
+ * @param variant The variant class, picture or initials.
+ * @param extra Whatever the caller passed.
+ * @returns The class attribute.
+ */
+function classes(variant: string, extra?: string): string {
+  return ['identity-avatar', variant, extra].filter(Boolean).join(' ');
+}
+
+/** The user fields this component reads. */
+interface AvatarUser {
+  id?: string | null;
+  fullname?: string | null;
+  portrait?: string | null;
+}
+
+const UserAvatar: React.FC<UserAvatarProps> = ({
+  size = '30px',
+  className,
+}) => {
+  const intl = useIntl();
+  const user = useSelector(
+    (state: any) => state.userProfile?.data,
+  ) as AvatarUser | null;
+  // Keyed by URL so that signing in as somebody else, or uploading a new
+  // portrait, gets a fresh attempt rather than inheriting the last failure.
+  const [failedPortrait, setFailedPortrait] = useState<string | null>(null);
+
+  const portrait = user?.portrait ?? null;
+  const label = intl.formatMessage(messages.avatar);
+
+  // Both walk the name or the userid character by character. Cheap, but this
+  // renders on every page in a toolbar that re-renders often.
+  const initials = useMemo(
+    () => initialsFor(user?.fullname || user?.id),
+    [user?.fullname, user?.id],
+  );
+  const background = useMemo(() => colorFor(user?.id), [user?.id]);
+
+  if (portrait && portrait !== failedPortrait) {
+    return (
+      <img
+        className={classes('identity-avatar--picture', className)}
+        style={{ width: size, height: size }}
+        src={flattenToAppURL(portrait)}
+        alt={label}
+        // A portrait that 404s -- deleted, or a stale URL after a rename --
+        // would otherwise render as the browser's broken-image glyph, which
+        // looks like a bug in the site rather than a missing photograph.
+        onError={() => setFailedPortrait(portrait)}
+      />
+    );
+  }
+
+  return (
+    <span
+      className={classes('identity-avatar--initials', className)}
+      style={{
+        width: size,
+        height: size,
+        // Inline because the colour is per user: a class per palette entry
+        // would be ten rules that exist only to avoid this attribute.
+        backgroundColor: background,
+        // The glyph should fill the circle at whatever size it is asked for.
+        fontSize: `calc(${size} / 2.4)`,
+      }}
+      // Decorative when there are no initials to read: an empty circle
+      // announced as "user avatar" is noise to a screen reader.
+      role={initials ? 'img' : undefined}
+      aria-label={initials ? label : undefined}
+      aria-hidden={initials ? undefined : true}
+    >
+      {initials}
+    </span>
+  );
+};
+
+export default UserAvatar;

package/src/components/UserMenu/UserMenuPlugs.stories.tsx

@@ -0,0 +1,101 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+
+import {
+  Pluggable,
+  PluggablesProvider,
+} from '@plone/volto/components/manage/Pluggable';
+import IdentitiesMenuItem from './IdentitiesMenuItem';
+import ProfileMenuItem from './ProfileMenuItem';
+import {
+  PersonalInformationMenuItem,
+  PreferencesMenuItem,
+  SiteSetupMenuItem,
+} from './UserMenuPlugs';
+import { LOADED, USER, withStore } from '../../stories/fixtures';
+import { withPersonalTools } from '../../storybook/withUserMenu';
+
+/**
+ * Volto's own menu entries, re-registered as plugs.
+ *
+ * Each renders nothing on its own -- a plug registers a renderer and returns
+ * null -- so the stories mount the pluggable that consumes them. What is
+ * worth looking at here is the *assembled* list: which entries appear, and
+ * in what order.
+ */
+const meta: Meta<typeof PreferencesMenuItem> = {
+  title: 'Identity/UserMenu/UserMenuPlugs',
+  component: PreferencesMenuItem,
+  decorators: [withPersonalTools],
+  parameters: { fullBleed: true },
+};
+export default meta;
+
+type Story = StoryObj<typeof PreferencesMenuItem>;
+
+const withState = (user: Record<string, unknown>, actions: unknown[] = []) =>
+  withStore({
+    userProfile: { ...LOADED, data: { ...USER, ...user } },
+    actions: { actions: { user: actions } },
+  });
+
+/**
+ * Every entry the add-on registers, in the menu's own markup.
+ *
+ * The markup comes from `withPersonalTools` rather than from here: it is
+ * Volto's, it has to sit inside `#toolbar` to be styled at all, and five
+ * copies of it across these stories is five things to fix when Volto moves
+ * one of them.
+ */
+const menu = () => (
+  <PluggablesProvider>
+    <PersonalInformationMenuItem />
+    <PreferencesMenuItem />
+    <SiteSetupMenuItem />
+    <IdentitiesMenuItem />
+    <ProfileMenuItem />
+    <ul>
+      <Pluggable
+        name="toolbar-user-menu"
+        params={{ loadComponent: () => {} }}
+      />
+    </ul>
+  </PluggablesProvider>
+);
+
+/**
+ * A member with a Profile of their own.
+ *
+ * "My profile" holds the first slot instead of Volto's Profile link, and
+ * "Sign-in methods" comes straight after Preferences because choosing how
+ * you get in is one.
+ */
+export const Member: Story = { render: menu, decorators: [withState({})] };
+
+/** A manager. Site Setup is last: it is about the site, not the person. */
+export const Manager: Story = {
+  render: menu,
+  decorators: [withState({}, [{ id: 'plone_setup' }])],
+};
+
+/**
+ * A member with no Profile.
+ *
+ * Volto's Profile link takes its slot back, leading to the member form at
+ * `/personal-information`.
+ */
+export const WithoutTheProfileLayer: Story = {
+  render: menu,
+  decorators: [withState({ profile_url: null })],
+};
+
+/**
+ * A user who has a Profile but is not stored as one.
+ *
+ * The same menu as above, and for the same reason: the member form is where
+ * a `source_users` account's fields are edited, whatever else exists.
+ */
+export const AProfileTheyAreNotStoredIn: Story = {
+  render: menu,
+  decorators: [withState({ source: 'source_users' })],
+};