@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/avatar/passport.json

@@ -0,0 +1,294 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Avatar",
+    "folder": "avatar",
+    "exports": [
+      "Avatar",
+      "AvatarGroup"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/identity.ts",
+      "core/index.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Avatar.tsx",
+      "react/AvatarGroup.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:b77d7514edf27df52d7bad888ae4ae24cac924a9f748dcce72ae8a92256ab54a"
+  },
+  "props": [
+    {
+      "name": "aria-describedby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-labelledby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "children",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "An icon or anything else to show instead of initials.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<AvatarSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "decorative",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Marks the avatar as decoration, for a name printed next to it.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "hidden",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "initials",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Overrides the text derived from `name`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Names the set, e.g. \"Assigned to\". A list of faces with no name says nothing.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<AvatarLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "max",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 4,
+      "origin": "derived",
+      "description": "How many slots there are, the overflow bubble included. Default 4.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "default": "",
+      "origin": "derived",
+      "description": "The person or thing. Used for the alternative text, for the initials and\nfor the colour, so the same person is always the same colour.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLSpanElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "role",
+      "type": "other",
+      "typeText": "AriaRole | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "shape",
+      "type": "enum",
+      "values": [
+        "circle",
+        "square"
+      ],
+      "typeText": "AvatarShape | undefined",
+      "required": false,
+      "default": "circle",
+      "origin": "derived",
+      "description": "Default `circle`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm",
+        "xl",
+        "xs"
+      ],
+      "typeText": "AvatarSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md` (32px).",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "src",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "status",
+      "type": "enum",
+      "values": [
+        "away",
+        "busy",
+        "offline",
+        "online"
+      ],
+      "typeText": "AvatarStatus | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "A presence dot in the corner.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "tabIndex",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "HTMLAttributes<HTMLSpanElement>",
+      "omitted": [
+        "children"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [],
+  "slots": [
+    "root",
+    "image",
+    "fallback",
+    "status",
+    "overflow"
+  ],
+  "states": [
+    {
+      "attr": "data-shape",
+      "values": [
+        "square"
+      ]
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm",
+        "xl",
+        "xs"
+      ]
+    },
+    {
+      "attr": "data-status",
+      "values": [
+        "away",
+        "busy",
+        "online"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 23,
+    "propsDescribed": 9,
+    "describedPct": 39,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/avatar/react/Avatar.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+import {
+  useMemo,
+  useState,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { colorIndex, initials as toInitials } from "../core/identity";
+import type { AvatarLocaleText, AvatarShape, AvatarSize, AvatarStatus } from "../core/types";
+import { defaultAvatarText } from "./locale";
+import { cx, type AvatarSlot } from "./props";
+
+/** Hues spread around the wheel; the fill and text are mixed from one of these. */
+const PALETTE = 8;
+
+export interface AvatarProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+  /**
+   * The person or thing. Used for the alternative text, for the initials and
+   * for the colour, so the same person is always the same colour.
+   */
+  name?: string;
+  src?: string;
+  /** Overrides the text derived from `name`. */
+  initials?: string;
+  /** An icon or anything else to show instead of initials. */
+  children?: ReactNode;
+  /** Default `md` (32px). */
+  size?: AvatarSize;
+  /** Default `circle`. */
+  shape?: AvatarShape;
+  /** A presence dot in the corner. */
+  status?: AvatarStatus;
+  /** Marks the avatar as decoration, for a name printed next to it. */
+  decorative?: boolean;
+  className?: string;
+  classNames?: Partial<Record<AvatarSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<AvatarLocaleText>;
+  ref?: Ref<HTMLSpanElement>;
+}
+
+/**
+ * A person in a small square or circle: their picture, or the letters of their
+ * name on a colour derived from it.
+ *
+ * An image that fails to load falls back to the initials rather than leaving a
+ * broken frame — which happens more than it should with avatar URLs that have
+ * expired or come from a third party.
+ */
+export function Avatar(props: AvatarProps) {
+  const {
+    ref,
+    name = "",
+    src,
+    initials: initialsProp,
+    children,
+    size = "md",
+    shape = "circle",
+    status,
+    decorative = false,
+    className,
+    classNames,
+    style,
+    localeText,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultAvatarText, ...localeText }), [localeText]);
+  const [failed, setFailed] = useState(false);
+  const letters = initialsProp ?? toInitials(name);
+  const showImage = Boolean(src) && !failed;
+
+  return (
+    <span
+      {...rest}
+      ref={ref}
+      className={cx("av-root", classNames?.root, className)}
+      style={{ ...style, "--av-hue-index": colorIndex(name || letters, PALETTE) } as CSSProperties}
+      data-size={size}
+      data-shape={shape}
+      data-status={status}
+      // Decoration when the name is printed beside it; otherwise the name is
+      // the alternative text, and there is no point repeating it.
+      role={decorative ? "presentation" : "img"}
+      aria-label={decorative ? undefined : name || undefined}
+      aria-hidden={decorative && !name ? "true" : undefined}
+    >
+      {showImage ? (
+        <img
+          className={cx("av-image", classNames?.image)}
+          src={src}
+          alt=""
+          loading="lazy"
+          decoding="async"
+          onError={() => setFailed(true)}
+        />
+      ) : (
+        <span className={cx("av-fallback", classNames?.fallback)} aria-hidden="true">
+          {children ?? letters}
+        </span>
+      )}
+
+      {status && (
+        <span
+          className={cx("av-status", classNames?.status)}
+          data-status={status}
+          // The dot is a fact about the person, so it is named rather than
+          // hidden — colour on its own tells a colour-blind user nothing.
+          role="img"
+          aria-label={text.status[status]}
+        />
+      )}
+    </span>
+  );
+}

package/source/components/avatar/react/AvatarGroup.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import { Children, useMemo, type CSSProperties, type ReactNode, type Ref } from "react";
+import { splitGroup } from "../core/identity";
+import type { AvatarLocaleText, AvatarShape, AvatarSize } from "../core/types";
+import { defaultAvatarText } from "./locale";
+import { cx, type AvatarGroupSlot } from "./props";
+
+export interface AvatarGroupProps {
+  children: ReactNode;
+  /** How many slots there are, the overflow bubble included. Default 4. */
+  max?: number;
+  /** Applied to the group; each Avatar keeps its own if it sets one. */
+  size?: AvatarSize;
+  shape?: AvatarShape;
+  /** Names the set, e.g. "Assigned to". A list of faces with no name says nothing. */
+  label?: string;
+  className?: string;
+  classNames?: Partial<Record<AvatarGroupSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<AvatarLocaleText>;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * Overlapping avatars with a "+3" at the end.
+ *
+ * The overflow bubble takes one of the `max` slots, so five people with
+ * `max={4}` show three faces and a "+2" — the alternative, four faces and a
+ * "+2", is five slots wide and quietly breaks a layout built for four.
+ */
+export function AvatarGroup(props: AvatarGroupProps) {
+  const {
+    ref,
+    children,
+    max = 4,
+    size,
+    shape,
+    label,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultAvatarText, ...localeText }), [localeText]);
+  const items = Children.toArray(children);
+  const { shown, overflow } = splitGroup(items, max);
+
+  return (
+    <div
+      ref={ref}
+      className={cx("av-group", classNames?.root, className)}
+      style={style}
+      data-size={size}
+      data-shape={shape}
+      role="group"
+      aria-label={label}
+    >
+      {shown}
+      {overflow > 0 && (
+        <span
+          className={cx("av-overflow", classNames?.overflow)}
+          data-size={size}
+          data-shape={shape}
+          role="img"
+          aria-label={text.more(overflow)}
+        >
+          +{overflow}
+        </span>
+      )}
+    </div>
+  );
+}

package/source/components/avatar/react/locale.ts

@@ -0,0 +1,11 @@
+import type { AvatarLocaleText } from "../core/types";
+
+export const defaultAvatarText: AvatarLocaleText = {
+  more: (count: number) => `${count} more`,
+  status: {
+    online: "Online",
+    away: "Away",
+    busy: "Busy",
+    offline: "Offline",
+  },
+};

package/source/components/avatar/react/props.ts

@@ -0,0 +1,6 @@
+export type AvatarSlot = "root" | "image" | "fallback" | "status";
+
+export type AvatarGroupSlot = "root" | "overflow";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";