@datalayer/core 1.2.18 → 1.2.20

package/lib/components/principal/Principal.js

@@ -226,9 +226,7 @@ export const Principal = ({ principal, isAdmin = false, avatarSize = 20, gap = 2
             hydratedEntity?.avatarUrl ||
             cachedPrincipal?.avatarUrl ||
             undefined,
-        avatarIcon: principal.avatarIcon ||
-            hydratedEntity?.avatarIcon ||
-            undefined,
+        avatarIcon: principal.avatarIcon || hydratedEntity?.avatarIcon || undefined,
         banner: principal.banner || hydratedEntity?.banner || undefined,
         firstName: principal.firstName ||
             hydratedEntity?.firstName ||
@@ -290,12 +288,6 @@ export const Principal = ({ principal, isAdmin = false, avatarSize = 20, gap = 2
         resolvedIsPublic,
         upsertCachedPrincipal,
     ]);
-    return (_jsxs(Box, { sx: {
-            display: 'inline-flex',
-            alignItems: 'center',
-            gap,
-            minWidth: 0,
-            ...sx,
-        }, children: [_jsx(PrincipalAvatar, { kind: resolvedPrincipal.kind, avatarUrl: resolvedPrincipal.avatarUrl, avatarIcon: resolvedPrincipal.avatarIcon, alt: resolvedPrincipal.displayName, size: avatarSize, square: square }), _jsx(PrincipalDetailsOverlay, { kind: resolvedPrincipal.kind, uid: resolvedPrincipal.uid, displayName: resolvedPrincipal.displayName, name: resolvedPrincipal.name, description: resolvedPrincipal.description, handle: resolvedPrincipal.handle, accountHandle: resolvedPrincipal.accountHandle, firstName: resolvedPrincipal.firstName, lastName: resolvedPrincipal.lastName, email: resolvedPrincipal.email, origin: resolvedPrincipal.origin, avatarUrl: resolvedPrincipal.avatarUrl, avatarIcon: resolvedPrincipal.avatarIcon, organizationName: teamOrganizationNameResolved, memberCount: teamMemberCount, isPublic: resolvedIsPublic, isAdmin: isAdmin })] }));
+    return (_jsxs(Box, { display: "inline-flex", alignItems: "center", gap: gap, minWidth: 0, sx: sx, children: [_jsx(PrincipalAvatar, { kind: resolvedPrincipal.kind, avatarUrl: resolvedPrincipal.avatarUrl, avatar: resolvedPrincipal.avatarIcon, alt: resolvedPrincipal.displayName, size: avatarSize, square: square }), _jsx(PrincipalDetailsOverlay, { kind: resolvedPrincipal.kind, uid: resolvedPrincipal.uid, displayName: resolvedPrincipal.displayName, name: resolvedPrincipal.name, description: resolvedPrincipal.description, handle: resolvedPrincipal.handle, accountHandle: resolvedPrincipal.accountHandle, firstName: resolvedPrincipal.firstName, lastName: resolvedPrincipal.lastName, email: resolvedPrincipal.email, origin: resolvedPrincipal.origin, avatarUrl: resolvedPrincipal.avatarUrl, avatar: resolvedPrincipal.avatarIcon, organizationName: teamOrganizationNameResolved, memberCount: teamMemberCount, isPublic: resolvedIsPublic, isAdmin: isAdmin })] }));
 };
 export default Principal;

package/lib/components/principal/PrincipalAppearance.d.ts

@@ -1,5 +1,6 @@
 import type { JSX } from 'react';
 import { type ComponentType, type SVGProps } from 'react';
+import { type AvatarChoice } from '../avatars/avatarChoice';
 /**
  * Who a principal is: a person, an organization, a team — or a service
  * principal, the one a deployed LOOP application acts in its own name through
@@ -114,7 +115,29 @@ export declare const PRINCIPAL_BANNERS: readonly [{
     readonly Component: ComponentType<any>;
 }];
 export declare function getPrincipalBannerForSeed(seed: string): string;
-export declare function getPrincipalAvatarIcon(name?: string): AvatarComponent | undefined;
+/** The names of the avatar set: the icons an avatar may be. */
+export declare const PRINCIPAL_AVATAR_ICON_NAMES: ReadonlySet<string>;
+/** The avatar a kept value names; throws `AvatarRefused` for anything else. */
+export declare function parsePrincipalAvatar(value: string): AvatarChoice;
+/**
+ * The avatar a kept value names, or `undefined` when there is none or it is
+ * refused — said once on the console, in its sentence: a picture that cannot
+ * be drawn is drawn as no choice, never as a broken page.
+ */
+export declare function principalAvatarOf(value: string | undefined): AvatarChoice | undefined;
+/**
+ * The drawing of a chosen avatar — an emoji or an icon of the set, by its
+ * kept value — on nothing: whatever holds it gives it its disc
+ * (`UserAvatar`, `PrincipalAvatar`, an application's face). `null` for no
+ * choice, or a refused one.
+ */
+export declare function ChosenAvatar({ avatar, size, label, }: {
+    avatar: string | undefined;
+    /** Its edge, in pixels. */
+    size: number;
+    /** What it is called for a screen reader; empty, it is decoration. */
+    label?: string;
+}): JSX.Element | null;
 export declare function PrincipalBannerImage({ banner, height, }: {
     banner?: string;
     height?: number;

package/lib/components/principal/PrincipalAppearance.js

@@ -1,7 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Suspense, lazy, useEffect, useState, } from 'react';
-import { Box, Button, Text, Tooltip } from '@primer/react';
+import { Box, useColorPalette } from '@datalayer/primer-addons';
+import { Button, SegmentedControl, Text, Tooltip } from '@primer/react';
 import { Dialog } from '@primer/react/experimental';
+import { AvatarRefused, emojiAvatar, iconAvatar, parseAvatar, } from '../avatars/avatarChoice.js';
+import { FACE_EMOJIS } from '../emoji/faceEmojis.js';
+import { FluentEmoji } from '../emoji/FluentEmoji.js';
 /**
  * An avatar icon, fetched the first time it is drawn.
  *
@@ -576,20 +580,59 @@ export function getPrincipalBannerForSeed(seed) {
     }
     return PRINCIPAL_BANNERS[Math.abs(hash) % PRINCIPAL_BANNERS.length].name;
 }
-export function getPrincipalAvatarIcon(name) {
-    return PRINCIPAL_AVATAR_ICONS.find(option => option.name === name)?.Icon;
+/** The names of the avatar set: the icons an avatar may be. */
+export const PRINCIPAL_AVATAR_ICON_NAMES = new Set(PRINCIPAL_AVATAR_ICONS.map(option => option.name));
+/** The avatar a kept value names; throws `AvatarRefused` for anything else. */
+export function parsePrincipalAvatar(value) {
+    return parseAvatar(value, PRINCIPAL_AVATAR_ICON_NAMES);
+}
+/**
+ * The avatar a kept value names, or `undefined` when there is none or it is
+ * refused — said once on the console, in its sentence: a picture that cannot
+ * be drawn is drawn as no choice, never as a broken page.
+ */
+export function principalAvatarOf(value) {
+    if (!value) {
+        return undefined;
+    }
+    try {
+        return parsePrincipalAvatar(value);
+    }
+    catch (error) {
+        if (error instanceof AvatarRefused) {
+            console.error(`Avatar refused: ${error.message}`);
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * The drawing of a chosen avatar — an emoji or an icon of the set, by its
+ * kept value — on nothing: whatever holds it gives it its disc
+ * (`UserAvatar`, `PrincipalAvatar`, an application's face). `null` for no
+ * choice, or a refused one.
+ */
+export function ChosenAvatar({ avatar, size, label = '', }) {
+    const choice = principalAvatarOf(avatar);
+    if (!choice) {
+        return null;
+    }
+    if (choice.kind === 'emoji') {
+        return _jsx(FluentEmoji, { emoji: choice.emoji, size: size, label: label });
+    }
+    const Icon = PRINCIPAL_AVATAR_ICONS.find(option => option.name === choice.name).Icon;
+    // The plain icon, coloured by the theme — never the `colored` variant,
+    // whose fixed palette belongs to the emoji it is drawn from.
+    return (_jsx(Icon, { size: size, themed: true, colormode: true, "aria-label": label || undefined, "aria-hidden": label ? undefined : true }));
 }
 export function PrincipalBannerImage({ banner, height = 180, }) {
     const Banner = PRINCIPAL_BANNERS.find(option => option.name === banner)?.Component;
     if (!Banner)
         return null;
-    return (_jsx(Box, { sx: {
+    return (_jsx(Box, { overflow: "hidden", borderRadius: 2, bg: "canvas.subtle", sx: {
             position: 'relative',
             width: '100%',
             height,
-            overflow: 'hidden',
-            borderRadius: 2,
-            bg: 'canvas.subtle',
             '& > svg': {
                 position: 'absolute',
                 inset: 0,
@@ -603,8 +646,26 @@ export function PrincipalBannerImage({ banner, height = 180, }) {
 }
 export function PrincipalAvatarPicker({ value, onChange, disabled = false, }) {
     const [open, setOpen] = useState(false);
-    const selected = PRINCIPAL_AVATAR_ICONS.find(option => option.name === value);
-    return (_jsxs(_Fragment, { children: [_jsx(Button, { type: "button", disabled: disabled, onClick: () => setOpen(true), children: selected ? `Change Avatar (${selected.label})` : 'Choose Avatar' }), open ? (_jsx(Dialog, { title: "Choose an Avatar", onClose: () => setOpen(false), 
+    const chosen = principalAvatarOf(value);
+    // The colour a chosen avatar is drawn in (`UserAvatar`'s `--datalayer-icon-fg`):
+    // the icons are offered as they will look.
+    const palette = useColorPalette();
+    // The tab the dialog opens on: what is chosen, the icons when nothing is.
+    const [tab, setTab] = useState(chosen?.kind === 'emoji' ? 'emoji' : 'icons');
+    const choose = (next) => {
+        onChange(next);
+        setOpen(false);
+    };
+    const selectedLabel = chosen?.kind === 'emoji'
+        ? chosen.emoji
+        : chosen
+            ? PRINCIPAL_AVATAR_ICONS.find(option => option.name === chosen.name)
+                ?.label
+            : undefined;
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { type: "button", disabled: disabled, onClick: () => {
+                    setTab(chosen?.kind === 'emoji' ? 'emoji' : 'icons');
+                    setOpen(true);
+                }, leadingVisual: chosen ? () => _jsx(ChosenAvatar, { avatar: value, size: 16 }) : undefined, children: selectedLabel ? `Change Avatar (${selectedLabel})` : 'Choose Avatar' }), open ? (_jsxs(Dialog, { title: "Choose an Avatar", onClose: () => setOpen(false), 
                 // The widest the dialog names — 640px — which is what it falls
                 // back to should the width below ever stop applying.
                 width: "xlarge", 
@@ -624,62 +685,49 @@ export function PrincipalAvatarPicker({ value, onChange, disabled = false, }) {
                         width: 'min(1080px, calc(100vw - 32px))',
                         maxWidth: 'none',
                     },
-                }, children: _jsx(Box, { sx: {
-                        display: 'grid',
+                }, children: [_jsxs(SegmentedControl, { "aria-label": "Avatar kind", sx: { mb: 3 }, onChange: index => setTab(index === 0 ? 'emoji' : 'icons'), children: [_jsx(SegmentedControl.Button, { selected: tab === 'emoji', children: "Emoji" }), _jsx(SegmentedControl.Button, { selected: tab === 'icons', children: "Icons" })] }), tab === 'emoji' ? (_jsx(Box, { display: "grid", gridTemplateColumns: [
+                            'repeat(6, minmax(0, 1fr))',
+                            'repeat(12, minmax(0, 1fr))',
+                        ], gap: 2, children: FACE_EMOJIS.map(emoji => {
+                            const next = emojiAvatar(emoji);
+                            const pressed = value === next;
+                            return (_jsx(Box, { as: "button", type: "button", "aria-label": emoji, "aria-pressed": pressed, onClick: () => choose(next), display: "flex", alignItems: "center", justifyContent: "center", height: 72, width: "100%", p: 0, appearance: "none", cursor: "pointer", border: "1px solid", borderRadius: 2, borderColor: pressed ? 'accent.emphasis' : 'border.default', bg: pressed ? 'accent.subtle' : 'canvas.default', hover: { borderColor: 'accent.emphasis' }, children: _jsx(FluentEmoji, { emoji: emoji, size: 44, label: "" }) }, emoji));
+                        }) })) : null, tab === 'icons' ? (_jsx(Box, { style: { '--datalayer-icon-fg': palette.primary }, display: "grid", 
                         // Twelve to a line, whatever the dialog is wide: the columns
                         // share it evenly and `minmax(0, …)` lets them shrink under
                         // their content, which a long name would otherwise widen.
                         gridTemplateColumns: [
                             'repeat(6, minmax(0, 1fr))',
                             'repeat(12, minmax(0, 1fr))',
-                        ],
-                        gap: 2,
-                    }, children: PRINCIPAL_AVATAR_ICONS.map(({ name, label, description, Icon }) => (
-                    // A button drawn as a card rather than a Primer `Button`: the
-                    // avatar is named under it, as the banners are under theirs.
-                    // The name under a card is clipped when it is long, and a
-                    // picture says only so much: the tooltip gives the whole name
-                    // and what the picture is of.
-                    _jsx(Tooltip, { text: description ? `${label} — ${description}` : label, direction: "n", children: _jsxs(Box, { as: "button", type: "button", "aria-label": description ? `${label} — ${description}` : label, "aria-pressed": value === name, onClick: () => {
-                                onChange(name);
-                                setOpen(false);
-                            }, sx: {
-                                display: 'block',
-                                width: '100%',
-                                p: 0,
-                                overflow: 'hidden',
-                                appearance: 'none',
-                                color: 'fg.default',
-                                cursor: 'pointer',
-                                border: '1px solid',
-                                borderRadius: 2,
-                                borderColor: value === name ? 'accent.emphasis' : 'border.default',
-                                bg: value === name ? 'accent.subtle' : 'canvas.default',
-                                ':hover': { borderColor: 'accent.emphasis' },
-                            }, children: [_jsx(Box, { sx: {
-                                        height: 72,
-                                        display: 'flex',
-                                        alignItems: 'center',
-                                        justifyContent: 'center',
-                                    }, children: _jsx(Icon, { size: 52, themed: true, colormode: true }) }), _jsx(Text, { sx: {
-                                        display: 'block',
-                                        px: 2,
-                                        py: 1,
-                                        fontSize: 0,
-                                        textAlign: 'center',
-                                        // A name too long for the card is cut rather than
-                                        // stretching the grid it sits in.
-                                        overflow: 'hidden',
-                                        textOverflow: 'ellipsis',
-                                        whiteSpace: 'nowrap',
-                                    }, children: label })] }) }, name))) }) })) : null] }));
+                        ], gap: 2, children: PRINCIPAL_AVATAR_ICONS.map(({ name, label, description, Icon }) => (
+                        // A button drawn as a card rather than a Primer `Button`: the
+                        // avatar is named under it, as the banners are under theirs.
+                        // The name under a card is clipped when it is long, and a
+                        // picture says only so much: the tooltip gives the whole name
+                        // and what the picture is of.
+                        _jsx(Tooltip, { text: description ? `${label} — ${description}` : label, direction: "n", children: _jsxs(Box, { as: "button", type: "button", "aria-label": description ? `${label} — ${description}` : label, "aria-pressed": value === iconAvatar(name), onClick: () => choose(iconAvatar(name)), display: "block", width: "100%", p: 0, overflow: "hidden", appearance: "none", color: "fg.default", cursor: "pointer", border: "1px solid", borderRadius: 2, borderColor: value === iconAvatar(name)
+                                    ? 'accent.emphasis'
+                                    : 'border.default', bg: value === iconAvatar(name)
+                                    ? 'accent.subtle'
+                                    : 'canvas.default', hover: { borderColor: 'accent.emphasis' }, children: [_jsx(Box, { height: 72, display: "flex", alignItems: "center", justifyContent: "center", children: _jsx(Icon, { size: 52, themed: true, colormode: true }) }), _jsx(Text, { sx: {
+                                            display: 'block',
+                                            px: 2,
+                                            py: 1,
+                                            fontSize: 0,
+                                            textAlign: 'center',
+                                            // A name too long for the card is cut rather than
+                                            // stretching the grid it sits in.
+                                            overflow: 'hidden',
+                                            textOverflow: 'ellipsis',
+                                            whiteSpace: 'nowrap',
+                                        }, children: label })] }) }, name))) })) : null] })) : null] }));
 }
 export function PrincipalBannerPicker({ value, onChange, disabled = false, showPreview = true, }) {
     const [open, setOpen] = useState(false);
     const [selectedName, setSelectedName] = useState(value);
     useEffect(() => setSelectedName(value), [value]);
     const selected = PRINCIPAL_BANNERS.find(option => option.name === selectedName);
-    return (_jsxs(_Fragment, { children: [showPreview && selected ? (_jsx(Box, { sx: { mb: 2 }, children: _jsx(PrincipalBannerImage, { banner: selected.name, height: 120 }) })) : null, _jsx(Button, { type: "button", disabled: disabled, onClick: () => setOpen(true), children: selected ? `Change Banner (${selected.label})` : 'Choose Banner' }), open ? (_jsx(Dialog, { title: "Choose a Banner", onClose: () => setOpen(false), width: "xlarge", 
+    return (_jsxs(_Fragment, { children: [showPreview && selected ? (_jsx(Box, { mb: 2, children: _jsx(PrincipalBannerImage, { banner: selected.name, height: 120 }) })) : null, _jsx(Button, { type: "button", disabled: disabled, onClick: () => setOpen(true), children: selected ? `Change Banner (${selected.label})` : 'Choose Banner' }), open ? (_jsx(Dialog, { title: "Choose a Banner", onClose: () => setOpen(false), width: "xlarge", 
                 // Under `&&` for the reason given on the avatar picker: a plain
                 // `sx` ties with the named width and may lose to it.
                 sx: {
@@ -687,38 +735,17 @@ export function PrincipalBannerPicker({ value, onChange, disabled = false, showP
                         width: 'min(960px, calc(100vw - 32px))',
                         maxWidth: 'none',
                     },
-                }, children: _jsx(Box, { sx: {
-                        display: 'grid',
-                        // Four to a row, so a banner is seen against its neighbours
-                        // rather than one at a time; one column on a narrow overlay,
-                        // where four would be four slivers.
-                        gridTemplateColumns: ['1fr', 'repeat(4, minmax(0, 1fr))'],
-                        gap: 3,
-                    }, children: PRINCIPAL_BANNERS.map(({ name, label, Component }) => (_jsxs(Box, { as: "button", type: "button", "aria-label": label, "aria-pressed": selectedName === name, onClick: () => {
+                }, children: _jsx(Box, { display: "grid", 
+                    // Four to a row, so a banner is seen against its neighbours
+                    // rather than one at a time; one column on a narrow overlay,
+                    // where four would be four slivers.
+                    gridTemplateColumns: ['1fr', 'repeat(4, minmax(0, 1fr))'], gap: 3, children: PRINCIPAL_BANNERS.map(({ name, label, Component }) => (_jsxs(Box, { as: "button", type: "button", "aria-label": label, "aria-pressed": selectedName === name, onClick: () => {
                             setSelectedName(name);
                             onChange(name);
                             setOpen(false);
-                        }, sx: {
-                            display: 'block',
-                            width: '100%',
-                            p: 0,
-                            overflow: 'hidden',
-                            appearance: 'none',
-                            color: 'fg.default',
-                            cursor: 'pointer',
-                            border: '1px solid',
-                            borderRadius: 2,
-                            borderColor: selectedName === name
-                                ? 'accent.emphasis'
-                                : 'border.default',
-                            bg: selectedName === name ? 'accent.subtle' : 'canvas.default',
-                            textAlign: 'left',
-                            ':hover': { borderColor: 'accent.emphasis' },
-                        }, children: [_jsx(Box, { sx: {
+                        }, display: "block", width: "100%", p: 0, overflow: "hidden", appearance: "none", color: "fg.default", cursor: "pointer", border: "1px solid", borderRadius: 2, borderColor: selectedName === name ? 'accent.emphasis' : 'border.default', bg: selectedName === name ? 'accent.subtle' : 'canvas.default', textAlign: "left", hover: { borderColor: 'accent.emphasis' }, children: [_jsx(Box, { aspectRatio: "3 / 1", overflow: "hidden", sx: {
                                     position: 'relative',
                                     width: '100%',
-                                    aspectRatio: '3 / 1',
-                                    overflow: 'hidden',
                                     '& > svg': {
                                         position: 'absolute',
                                         inset: 0,

package/lib/components/principal/PrincipalAvatar.d.ts

@@ -4,14 +4,12 @@ export type PrincipalAvatarKind = PrincipalType;
 export type PrincipalAvatarProps = {
     kind: PrincipalAvatarKind;
     avatarUrl?: string;
-    avatarIcon?: string;
     /**
-     * A literal emoji this platform draws for a face of its own — an agent —
-     * rather than a person's chosen picture or icon. Checked before
-     * `avatarUrl`/`avatarIcon`, and only for `kind: 'personal'`: an agent is a
-     * personal-shaped seat in every roster it appears in today.
+     * The chosen avatar, as it is kept: `emoji:…` or
+     * `@datalayer/icons-react:…` (`components/avatars/avatarChoice`). An
+     * agent's face is its emoji, as `emoji:…`.
      */
-    avatarEmoji?: string;
+    avatar?: string;
     alt?: string;
     size?: number;
     square?: boolean;
@@ -24,5 +22,5 @@ export type PrincipalAvatarProps = {
     ring?: boolean;
     className?: string;
 };
-export declare function PrincipalAvatar({ kind, avatarUrl, avatarIcon, avatarEmoji, alt, size, square, ring, className, }: PrincipalAvatarProps): JSX.Element;
+export declare function PrincipalAvatar({ kind, avatarUrl, avatar, alt, size, square, ring, className, }: PrincipalAvatarProps): JSX.Element;
 export default PrincipalAvatar;

package/lib/components/principal/PrincipalAvatar.js

@@ -1,18 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Box } from '@datalayer/primer-addons';
+import { EntityAvatar } from '@datalayer/primer-addons';
 import { OrganizationIcon, PeopleIcon } from '@primer/octicons-react';
 import { UserAvatar } from '../avatars/index.js';
-import { getPrincipalAvatarIcon, } from './PrincipalAppearance.js';
+import { ChosenAvatar, principalAvatarOf, } from './PrincipalAppearance.js';
 function getFallbackIconSize(size) {
     return Math.max(12, Math.round(size * 0.62));
 }
-export function PrincipalAvatar({ kind, avatarUrl, avatarIcon, avatarEmoji, alt, size = 20, square = false, ring = false, className, }) {
-    const SelectedIcon = getPrincipalAvatarIcon(avatarIcon);
-    // Outside the edge rather than a border, so the avatar keeps the size it
-    // was asked for — see `UserAvatar`, which draws its ring the same way.
-    const ringSx = ring
-        ? { boxShadow: '0 0 0 1px var(--borderColor-default, currentColor)' }
-        : undefined;
+export function PrincipalAvatar({ kind, avatarUrl, avatar, alt, size = 20, square = false, ring = false, className, }) {
+    const chosen = principalAvatarOf(avatar);
+    const shape = square ? 'rounded' : 'circle';
     /*
      * A person is drawn by `UserAvatar`, whatever they wear.
      *
@@ -25,37 +21,15 @@ export function PrincipalAvatar({ kind, avatarUrl, avatarIcon, avatarEmoji, alt,
     // A service principal — an application's — is drawn as a person is: its
     // chosen avatar, or its emoji, on the same disc (LOOP I-07).
     if (kind === 'personal' || kind === 'service') {
-        return (_jsx(UserAvatar, { avatarUrl: avatarUrl, avatarIcon: avatarIcon, avatarEmoji: avatarEmoji, size: size, square: square, iconSize: getFallbackIconSize(size), ring: ring, className: className }));
+        return (_jsx(UserAvatar, { avatarUrl: avatarUrl, avatar: avatar, size: size, square: square, iconSize: getFallbackIconSize(size), ring: ring, className: className }));
     }
-    if (SelectedIcon) {
-        return (_jsx(Box, { className: className, sx: {
-                width: size,
-                height: size,
-                display: 'inline-flex',
-                alignItems: 'center',
-                justifyContent: 'center',
-                overflow: 'hidden',
-                borderRadius: square ? 2 : '50%',
-                // The disc of `UserAvatar`, for the same reason: the shape is what
-                // says "avatar", and an icon drawn on nothing shows none of it.
-                bg: 'accent.subtle',
-                ...ringSx,
-            }, "aria-label": alt || `${kind} avatar`, children: _jsx(SelectedIcon, { size: getFallbackIconSize(size), themed: true, colormode: true }) }));
+    if (chosen) {
+        return (
+        // The disc of `UserAvatar`, for the same reason: the shape is what says
+        // "avatar", and an icon drawn on nothing shows none of it.
+        _jsx(EntityAvatar, { className: className, size: size, shape: shape, ring: ring, alt: alt || `${kind} avatar`, children: _jsx(ChosenAvatar, { avatar: avatar, size: getFallbackIconSize(size) }) }));
     }
-    const iconSize = getFallbackIconSize(size);
-    const borderRadius = square ? 2 : '50%';
     const Icon = kind === 'team' ? PeopleIcon : OrganizationIcon;
-    return (_jsx(Box, { className: className, sx: {
-            width: size,
-            height: size,
-            display: 'inline-flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-            bg: 'canvas.subtle',
-            borderRadius,
-            border: '1px solid',
-            borderColor: 'border.default',
-            ...ringSx,
-        }, "aria-label": alt || (kind === 'team' ? 'Team' : 'Organization'), children: _jsx(Icon, { size: iconSize }) }));
+    return (_jsx(EntityAvatar, { className: className, size: size, shape: shape, ring: ring, ground: "canvas", alt: alt || (kind === 'team' ? 'Team' : 'Organization'), children: _jsx(Icon, { size: getFallbackIconSize(size) }) }));
 }
 export default PrincipalAvatar;

package/lib/components/principal/PrincipalBadge.js

@@ -4,7 +4,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Distributed under the terms of the Modified BSD License.
  */
 import { useMemo } from 'react';
-import { Box, Label, Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { Label, Text } from '@primer/react';
 import { useCache } from '../../hooks/index.js';
 import { useIAMStore } from '../../state/substates/index.js';
 import { useSelectedPrincipal } from '../../hooks/useSelectedPrincipal.js';
@@ -220,17 +221,6 @@ export const PrincipalBadge = ({ principal: providedPrincipal, showPrincipalLabe
         resolvedOrganization?.avatarIcon,
         resolvedUser?.origin,
     ]);
-    return (_jsxs(Box, { sx: {
-            display: 'inline-flex',
-            alignItems: 'center',
-            gap: 2,
-            px: 2,
-            py: 1,
-            border: '1px solid',
-            borderColor: 'border.default',
-            borderRadius: 2,
-            bg: 'canvas.subtle',
-            ...sx,
-        }, children: [showPrincipalLabel && (_jsx(Label, { size: "small", variant: "accent", children: principalLabel })), showApplyingToText && (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Applying to" })), _jsx(Principal, { principal: principal, isAdmin: isAdmin }), showOriginLabel && principal.origin && (_jsx(Label, { size: "small", variant: "secondary", children: principal.origin }))] }));
+    return (_jsxs(Box, { display: "inline-flex", alignItems: "center", gap: 2, px: 2, py: 1, border: "1px solid", borderColor: "border.default", borderRadius: 2, bg: "canvas.subtle", sx: sx, children: [showPrincipalLabel && (_jsx(Label, { size: "small", variant: "accent", children: principalLabel })), showApplyingToText && (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Applying to" })), _jsx(Principal, { principal: principal, isAdmin: isAdmin }), showOriginLabel && principal.origin && (_jsx(Label, { size: "small", variant: "secondary", children: principal.origin }))] }));
 };
 export default PrincipalBadge;

package/lib/components/principal/PrincipalBanner.js

@@ -8,7 +8,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * (user, organization, or team) with a colored visual so a user
  * can immediately see which principal a settings page applies to.
  */
-import { Box, Label, Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { Label, Text } from '@primer/react';
 import { OrganizationIcon, PeopleIcon, PersonIcon, } from '@primer/octicons-react';
 import { useSelectedPrincipal } from '../../hooks/useSelectedPrincipal.js';
 import { useIAMStore } from '../../state/substates/index.js';
@@ -39,33 +40,7 @@ export const PrincipalBanner = ({ caption, rightContent, }) => {
             ? 'attention.muted'
             : 'accent.muted';
     const fg = isOrganization ? 'done.fg' : isTeam ? 'attention.fg' : 'accent.fg';
-    return (_jsxs(Box, { sx: {
-            display: 'flex',
-            alignItems: 'center',
-            gap: 3,
-            p: 3,
-            border: '1px solid',
-            borderColor,
-            borderRadius: 2,
-            bg,
-        }, children: [_jsx(Box, { sx: {
-                    width: 40,
-                    height: 40,
-                    display: 'flex',
-                    alignItems: 'center',
-                    justifyContent: 'center',
-                    borderRadius: '50%',
-                    bg: 'canvas.default',
-                    border: '1px solid',
-                    borderColor,
-                    color: fg,
-                    flex: '0 0 auto',
-                }, children: _jsx(Icon, { size: 20 }) }), _jsxs(Box, { sx: { minWidth: 0, flex: 1 }, children: [_jsxs(Box, { sx: {
-                            display: 'flex',
-                            alignItems: 'center',
-                            gap: 2,
-                            flexWrap: 'wrap',
-                        }, children: [_jsx(Text, { sx: {
+    return (_jsxs(Box, { display: "flex", alignItems: "center", gap: 3, p: 3, border: "1px solid", borderColor: borderColor, borderRadius: 2, bg: bg, children: [_jsx(Box, { width: 40, height: 40, display: "flex", alignItems: "center", justifyContent: "center", borderRadius: "50%", bg: "canvas.default", border: "1px solid", borderColor: borderColor, color: fg, flex: "0 0 auto", children: _jsx(Icon, { size: 20 }) }), _jsxs(Box, { minWidth: 0, flex: 1, children: [_jsxs(Box, { display: "flex", alignItems: "center", gap: 2, flexWrap: "wrap", children: [_jsx(Text, { sx: {
                                     color: 'fg.muted',
                                     fontSize: 0,
                                     textTransform: 'uppercase',
@@ -76,9 +51,6 @@ export const PrincipalBanner = ({ caption, rightContent, }) => {
                                 ? 'Organization'
                                 : isTeam
                                     ? 'Team'
-                                    : 'User' }), caption && (_jsx(Text, { as: "p", sx: { m: 0, mt: 1, color: 'fg.muted', fontSize: 1 }, children: caption }))] }), rightContent ? (_jsx(Box, { sx: {
-                    flex: ['1 1 100%', '0 0 auto'],
-                    width: ['100%', 'min(640px, 58%)'],
-                }, children: rightContent })) : null] }));
+                                    : 'User' }), caption && (_jsx(Text, { as: "p", sx: { m: 0, mt: 1, color: 'fg.muted', fontSize: 1 }, children: caption }))] }), rightContent ? (_jsx(Box, { flex: ['1 1 100%', '0 0 auto'], width: ['100%', 'min(640px, 58%)'], children: rightContent })) : null] }));
 };
 export default PrincipalBanner;

package/lib/components/principal/PrincipalDetailsOverlay.d.ts

@@ -14,14 +14,11 @@ export type PrincipalDetailsOverlayProps = {
     email?: string;
     origin?: string;
     avatarUrl?: string;
-    avatarIcon?: string;
     /**
-     * A literal emoji, for a face this platform draws rather than a person's
-     * own choice of picture or icon — an agent, checked before `avatarUrl`/
-     * `avatarIcon` since the emoji is its real identity here, not a
-     * placeholder standing in for one.
+     * The chosen avatar, as it is kept: `emoji:…` (an agent's face is its
+     * emoji) or `@datalayer/icons-react:…`.
      */
-    avatarEmoji?: string;
+    avatar?: string;
     /** Team-specific: parent organization display name. */
     organizationName?: string;
     /** Team-specific: number of members. */
@@ -59,7 +56,7 @@ export declare function buildPrincipalProfilePath({ kind, uid, handle, accountHa
  * anchored on an avatar ({@link PrincipalHoverCard}) both render this, so
  * the two never drift.
  */
-export declare function PrincipalDetailsCard({ kind, uid, displayName, name, description, handle, accountHandle, firstName, lastName, email, origin, avatarUrl, avatarIcon, avatarEmoji, organizationName, memberCount, isPublic, isAdmin, onNavigate, }: PrincipalDetailsOverlayProps): JSX.Element;
+export declare function PrincipalDetailsCard({ kind, uid, displayName, name, description, handle, accountHandle, firstName, lastName, email, origin, avatarUrl, avatar, organizationName, memberCount, isPublic, isAdmin, onNavigate, }: PrincipalDetailsOverlayProps): JSX.Element;
 /**
  * A principal's details, shown from a click on their name.
  *

package/lib/components/principal/PrincipalDetailsOverlay.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { ActionMenu, Box, Button, Label, Text, ThemeProvider, } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { ActionMenu, Button, Label, Text, ThemeProvider } from '@primer/react';
 import { useNavigate } from '../../hooks/index.js';
 import { PrincipalAvatar } from './PrincipalAvatar.js';
 import { displayHandleText } from '../display/DisplayHandle.js';
@@ -88,7 +89,7 @@ export function buildPrincipalProfilePath({ kind, uid, handle, accountHandle, is
  * anchored on an avatar ({@link PrincipalHoverCard}) both render this, so
  * the two never drift.
  */
-export function PrincipalDetailsCard({ kind, uid, displayName, name, description, handle, accountHandle, firstName, lastName, email, origin, avatarUrl, avatarIcon, avatarEmoji, organizationName, memberCount, isPublic, isAdmin = false, onNavigate, }) {
+export function PrincipalDetailsCard({ kind, uid, displayName, name, description, handle, accountHandle, firstName, lastName, email, origin, avatarUrl, avatar, organizationName, memberCount, isPublic, isAdmin = false, onNavigate, }) {
     const navigate = useNavigate();
     // Where a profile or organization link goes: the router of this subtree,
     // unless the caller knows of one that can actually serve it — see
@@ -139,18 +140,13 @@ export function PrincipalDetailsCard({ kind, uid, displayName, name, description
     const organizationPath = teamOrganizationHandle
         ? `/${teamOrganizationHandle.replace(/^@+/, '')}`
         : '';
-    return (_jsxs(Box, { sx: { display: 'grid', gap: 3, p: 4, minWidth: 420 }, children: [_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, children: [_jsx(PrincipalAvatar, { kind: kind, avatarUrl: avatarUrl, avatarIcon: avatarIcon, avatarEmoji: avatarEmoji, alt: normalizedDisplayName, size: 40, 
+    return (_jsxs(Box, { display: "grid", gap: 3, p: 4, minWidth: 420, children: [_jsxs(Box, { display: "flex", alignItems: "center", gap: 2, children: [_jsx(PrincipalAvatar, { kind: kind, avatarUrl: avatarUrl, avatar: avatar, alt: normalizedDisplayName, size: 40, 
                         // The card sets the avatar on its own ground, the same colour
                         // the avatar itself is on: without an edge of its own it has
                         // no visible shape at all. Round, and ringed.
-                        square: false, ring: true }), _jsxs(Box, { sx: { display: 'grid', gap: 0.5 }, children: [_jsx(Text, { sx: { fontWeight: 'semibold' }, children: normalizedDisplayName }), kind === 'team' ? (teamHandleOnly ? (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: [displayHandleText(teamHandleOnly), teamOrganizationHandle
+                        square: false, ring: true }), _jsxs(Box, { display: "grid", gap: 0.5, children: [_jsx(Text, { sx: { fontWeight: 'semibold' }, children: normalizedDisplayName }), kind === 'team' ? (teamHandleOnly ? (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: [displayHandleText(teamHandleOnly), teamOrganizationHandle
                                         ? ` · @${teamOrganizationHandle.replace(/^@+/, '')}`
-                                        : ''] })) : null) : resolvedHandle ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: displayHandleText(resolvedHandle) })) : null] })] }), _jsxs(Box, { sx: {
-                    display: 'grid',
-                    gridTemplateColumns: '110px 1fr',
-                    gap: 1,
-                    alignItems: 'baseline',
-                }, children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Kind" }), _jsx(Text, { sx: { fontSize: 1 }, children: kind }), resolvedHandle && kind !== 'team' ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Handle" }), _jsx(Text, { sx: { fontSize: 1 }, children: displayHandleText(resolvedHandle) })] })) : null, normalizedUid ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "UID" }), _jsx(Text, { sx: { fontSize: 1 }, children: normalizedUid })] })) : null, kind === 'personal' ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "First name" }), _jsx(Text, { sx: { fontSize: 1 }, children: firstName || 'N/A' }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Last name" }), _jsx(Text, { sx: { fontSize: 1 }, children: lastName || 'N/A' }), email ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Email" }), _jsx(Text, { sx: { fontSize: 1 }, children: email })] })) : null, _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Origin" }), _jsx(Label, { size: "small", variant: "secondary", title: normalizedOrigin, sx: {
+                                        : ''] })) : null) : resolvedHandle ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: displayHandleText(resolvedHandle) })) : null] })] }), _jsxs(Box, { display: "grid", gridTemplateColumns: "110px 1fr", gap: 1, alignItems: "baseline", children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Kind" }), _jsx(Text, { sx: { fontSize: 1 }, children: kind }), resolvedHandle && kind !== 'team' ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Handle" }), _jsx(Text, { sx: { fontSize: 1 }, children: displayHandleText(resolvedHandle) })] })) : null, normalizedUid ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "UID" }), _jsx(Text, { sx: { fontSize: 1 }, children: normalizedUid })] })) : null, kind === 'personal' ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "First name" }), _jsx(Text, { sx: { fontSize: 1 }, children: firstName || 'N/A' }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Last name" }), _jsx(Text, { sx: { fontSize: 1 }, children: lastName || 'N/A' }), email ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Email" }), _jsx(Text, { sx: { fontSize: 1 }, children: email })] })) : null, _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "Origin" }), _jsx(Label, { size: "small", variant: "secondary", title: normalizedOrigin, sx: {
                                     justifySelf: 'start',
                                     width: 'fit-content',
                                     maxWidth: '100%',
@@ -166,7 +162,7 @@ export function PrincipalDetailsCard({ kind, uid, displayName, name, description
                                     overflow: 'hidden',
                                     textOverflow: 'ellipsis',
                                     whiteSpace: 'nowrap',
-                                }, children: normalizedOrigin })] }))] }), _jsxs(Box, { sx: { display: 'flex', justifyContent: 'flex-end', gap: 2 }, children: [kind === 'team' && organizationPath ? (_jsx(Button, { size: "small", variant: "invisible", onClick: () => go(organizationPath), children: "View Organization" })) : null, _jsx(Button, { size: "small", onClick: () => go(targetPath), disabled: !targetPath, children: "View Profile" })] })] }));
+                                }, children: normalizedOrigin })] }))] }), _jsxs(Box, { display: "flex", justifyContent: "flex-end", gap: 2, children: [kind === 'team' && organizationPath ? (_jsx(Button, { size: "small", variant: "invisible", onClick: () => go(organizationPath), children: "View Organization" })) : null, _jsx(Button, { size: "small", onClick: () => go(targetPath), disabled: !targetPath, children: "View Profile" })] })] }));
 }
 /**
  * A principal's details, shown from a click on their name.
@@ -179,18 +175,6 @@ export function PrincipalDetailsOverlay(props) {
         normalize(props.handle) ||
         normalize(props.uid) ||
         'Principal';
-    return (_jsx(ThemeProvider, { children: _jsxs(ActionMenu, { children: [_jsx(ActionMenu.Anchor, { children: _jsx(Box, { as: "button", type: "button", sx: {
-                            fontWeight: 'semibold',
-                            color: 'accent.fg',
-                            textDecoration: 'underline',
-                            background: 'transparent',
-                            border: 0,
-                            padding: 0,
-                            margin: 0,
-                            cursor: 'pointer',
-                            ':hover': {
-                                textDecoration: 'underline',
-                            },
-                        }, children: normalizedDisplayName }) }), _jsx(ActionMenu.Overlay, { width: "large", children: _jsx(PrincipalDetailsCard, { ...props }) })] }) }));
+    return (_jsx(ThemeProvider, { children: _jsxs(ActionMenu, { children: [_jsx(ActionMenu.Anchor, { children: _jsx(Box, { as: "button", type: "button", fontWeight: "semibold", color: "accent.fg", textDecoration: "underline", background: "transparent", border: 0, padding: 0, margin: 0, cursor: "pointer", hover: { textDecoration: 'underline' }, children: normalizedDisplayName }) }), _jsx(ActionMenu.Overlay, { width: "large", children: _jsx(PrincipalDetailsCard, { ...props }) })] }) }));
 }
 export default PrincipalDetailsOverlay;