@arbor-education/design-system.components 0.5.4 → 0.6.0

package/src/components/avatarGroup/AvatarGroup.tsx

@@ -0,0 +1,127 @@
+import classNames from 'classnames';
+import { Avatar, type AvatarSize } from 'Components/avatar/Avatar';
+import React from 'react';
+import { partitionAvatarGroupOverflow, type AvatarGroupListOrder } from './avatarGroupOverflow';
+import { collectAvatarsFromChildren } from './collectAvatarGroupChildren';
+import { useAvatarGroupItems, type AvatarGroupItem } from './useAvatarGroupItems';
+
+export type { AvatarGroupItem, AvatarGroupListOrder };
+
+export type AvatarGroupOverflowCountProps = {
+  count: number;
+  overflowCountLabel?: string | ((count: number) => string);
+  className?: string;
+  presentAllUpdatesToScreenReader?: boolean;
+};
+
+function resolveOverflowAriaLabel(
+  count: number,
+  overflowCountLabel?: string | ((c: number) => string),
+): string {
+  if (typeof overflowCountLabel === 'function') {
+    return overflowCountLabel(count);
+  }
+  if (typeof overflowCountLabel === 'string') {
+    return overflowCountLabel;
+  }
+  return `plus ${count} more`;
+}
+
+function AvatarGroupOverflowCount({
+  count,
+  overflowCountLabel,
+  className,
+  presentAllUpdatesToScreenReader = false,
+}: AvatarGroupOverflowCountProps) {
+  return (
+    <span
+      role="status"
+      className={classNames('ds-avatar-group__overflow-count', className)}
+      aria-label={resolveOverflowAriaLabel(count, overflowCountLabel)}
+      aria-live={presentAllUpdatesToScreenReader ? 'polite' : undefined}
+      aria-atomic={presentAllUpdatesToScreenReader ? 'true' : undefined}
+    >
+      +
+      {count}
+    </span>
+  );
+}
+
+type AvatarGroupSharedProps = {
+  showMaxItems?: number;
+  listOrder?: AvatarGroupListOrder;
+  label?: string;
+  overflowCountLabel?: string | ((count: number) => string);
+  presentAllUpdatesToScreenReader?: boolean;
+  size?: AvatarSize;
+  className?: string;
+};
+
+export type AvatarGroupProps = AvatarGroupSharedProps
+  & (
+    | { items: readonly AvatarGroupItem[]; children?: undefined }
+    | { children: React.ReactNode; items?: undefined }
+  )
+  & Omit<React.HTMLAttributes<HTMLUListElement>, 'children'>;
+
+const AvatarGroupRoot = React.forwardRef<HTMLUListElement, AvatarGroupProps>(({
+  items,
+  children,
+  size: groupSize,
+  showMaxItems,
+  listOrder = 'ascending',
+  label,
+  overflowCountLabel,
+  presentAllUpdatesToScreenReader = false,
+  className,
+  ...rest
+}: AvatarGroupProps, ref) => {
+  const sourceItems = React.useMemo(() => {
+    if (children != null) {
+      return collectAvatarsFromChildren(children);
+    }
+    return items ?? [];
+  }, [children, items]);
+
+  const normalized = useAvatarGroupItems(sourceItems, groupSize);
+  const { visibleItems, overflowCount } = React.useMemo(
+    () => partitionAvatarGroupOverflow(normalized, showMaxItems, listOrder),
+    [normalized, showMaxItems, listOrder],
+  );
+
+  return (
+    <ul
+      ref={ref}
+      role="list"
+      className={classNames('ds-avatar-group', className)}
+      aria-label={label}
+      {...rest}
+    >
+      {visibleItems.map(entry => (
+        <li
+          key={entry.key}
+          className="ds-avatar-group__item"
+        >
+          <Avatar {...entry.avatarProps} />
+        </li>
+      ))}
+      {overflowCount > 0
+        ? (
+            <li className="ds-avatar-group__overflow">
+              <AvatarGroupOverflowCount
+                count={overflowCount}
+                overflowCountLabel={overflowCountLabel}
+                presentAllUpdatesToScreenReader={presentAllUpdatesToScreenReader}
+              />
+            </li>
+          )
+        : null}
+    </ul>
+  );
+});
+
+AvatarGroupRoot.displayName = 'AvatarGroup';
+
+export const AvatarGroup = Object.assign(AvatarGroupRoot, {
+  OverflowCount: AvatarGroupOverflowCount,
+});

package/src/components/avatarGroup/avatarGroup.scss

@@ -0,0 +1,31 @@
+.ds-avatar-group {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.ds-avatar-group__item {
+  flex-shrink: 0;
+
+  &:not(:first-child) {
+    margin-inline-start: var(--avatar-group-overlap);
+  }
+}
+
+.ds-avatar-group__overflow {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  margin-inline-start: var(--avatar-group-overlap);
+}
+
+.ds-avatar-group__overflow-count {
+  display: inline-flex;
+  align-items: center;
+  font-size: var(--avatar-group-overflow-count-font-size);
+  font-weight: 600;
+  margin-inline-start: var(--spacing-small);
+}

package/src/components/avatarGroup/avatarGroupOverflow.ts

@@ -0,0 +1,29 @@
+import type { AvatarGroupNormalizedEntry } from './useAvatarGroupItems';
+
+export type AvatarGroupListOrder = 'ascending' | 'descending';
+
+export type AvatarGroupOverflowPartition = {
+  visibleItems: AvatarGroupNormalizedEntry[];
+  overflowCount: number;
+};
+
+export function partitionAvatarGroupOverflow(
+  items: readonly AvatarGroupNormalizedEntry[],
+  showMaxItems: number | undefined,
+  listOrder: AvatarGroupListOrder = 'ascending',
+): AvatarGroupOverflowPartition {
+  const total = items.length;
+  const maxItems
+    = showMaxItems == null || !Number.isFinite(showMaxItems) || showMaxItems < 0
+      ? total
+      : Math.floor(showMaxItems);
+  const visibleCount = Math.min(total, maxItems);
+
+  const overflowCount = total - visibleCount;
+  const startIndex = listOrder === 'ascending' ? 0 : overflowCount;
+
+  return {
+    visibleItems: items.slice(startIndex, startIndex + visibleCount),
+    overflowCount,
+  };
+}

package/src/components/avatarGroup/collectAvatarGroupChildren.ts

@@ -0,0 +1,30 @@
+import { Avatar, type AvatarProps } from 'Components/avatar/Avatar';
+import React from 'react';
+import type { AvatarGroupItem } from './useAvatarGroupItems';
+
+export function collectAvatarsFromChildren(children: React.ReactNode): AvatarGroupItem[] {
+  const out: AvatarGroupItem[] = [];
+
+  const walk = (node: React.ReactNode) => {
+    React.Children.forEach(node, (child) => {
+      if (child == null || typeof child === 'boolean') {
+        return;
+      }
+      if (React.isValidElement(child) && child.type === React.Fragment) {
+        walk((child.props as { children?: React.ReactNode }).children);
+        return;
+      }
+      if (React.isValidElement<AvatarProps>(child) && child.type === Avatar) {
+        out.push(child);
+        return;
+      }
+
+      if (React.isValidElement(child) && process.env.NODE_ENV !== 'production') {
+        console.warn('AvatarGroup only collects `<Avatar />` children when using the children API.');
+      }
+    });
+  };
+
+  walk(children);
+  return out;
+}

package/src/components/avatarGroup/useAvatarGroupItems.ts

@@ -0,0 +1,39 @@
+import { Avatar, type AvatarProps, type AvatarSize } from 'Components/avatar/Avatar';
+import React from 'react';
+
+export type AvatarGroupItem = React.ReactElement<AvatarProps> | AvatarProps;
+
+export type AvatarGroupNormalizedEntry = {
+  key: string;
+  avatarProps: AvatarProps;
+};
+
+export function useAvatarGroupItems(
+  items: readonly AvatarGroupItem[],
+  groupSize: AvatarSize | undefined,
+): AvatarGroupNormalizedEntry[] {
+  return React.useMemo(
+    () =>
+      items.map((item, index) => {
+        if (React.isValidElement<AvatarProps>(item) && item.type === Avatar) {
+          return {
+            key: item.key != null ? String(item.key) : String(index),
+            avatarProps: {
+              ...item.props,
+              size: groupSize ?? item.props.size,
+            },
+          };
+        }
+
+        const props = item as AvatarProps;
+        return {
+          key: String(index),
+          avatarProps: {
+            ...props,
+            size: groupSize ?? props.size,
+          },
+        };
+      }),
+    [items, groupSize],
+  );
+}

package/src/components/heading/heading.scss

@@ -17,7 +17,7 @@
 }
 
 h1 {
-  &.ds-heading, .ds-editable-text__button, .ds-editable-text__input {
+  &.ds-heading, &.ds-heading .ds-heading__inner-container, .ds-editable-text__button, .ds-editable-text__input {
     font-family: var(--type-headings-h1-family);
     font-size: var(--type-headings-h1-size);
     font-weight: var(--type-headings-h1-weight);
@@ -26,7 +26,7 @@ h1 {
 }
 
 h2 {
-  &.ds-heading, .ds-editable-text__button, .ds-editable-text__input {
+  &.ds-heading, &.ds-heading .ds-heading__inner-container, .ds-editable-text__button, .ds-editable-text__input {
     font-family: var(--type-headings-h2-family);
     font-size: var(--type-headings-h2-size);
     font-weight: var(--type-headings-h2-weight);
@@ -35,7 +35,7 @@ h2 {
 }
 
 h3 {
-  &.ds-heading, .ds-editable-text__button, .ds-editable-text__input {
+  &.ds-heading, &.ds-heading .ds-heading__inner-container, .ds-editable-text__button, .ds-editable-text__input {
     font-family: var(--type-headings-h3-family);
     font-size: var(--type-headings-h3-size);
     font-weight: var(--type-headings-h3-weight);
@@ -44,7 +44,7 @@ h3 {
 }
 
 h4 {
-  &.ds-heading, .ds-editable-text__button, .ds-editable-text__input {
+  &.ds-heading, &.ds-heading .ds-heading__inner-container, .ds-editable-text__button, .ds-editable-text__input {
     font-family: var(--type-headings-h4-family);
     font-size: var(--type-headings-h4-size);
     font-weight: var(--type-headings-h4-weight);