@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/alert/passport.json

@@ -0,0 +1,250 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Alert",
+    "folder": "alert",
+    "exports": [
+      "Alert"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/index.ts",
+      "core/live.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Alert.tsx",
+      "react/icons.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:fb3baa3da19c07b09a7bebf3c96c8360ce4612c4b882f6dd2f95aa0616b6bead"
+  },
+  "props": [
+    {
+      "name": "actions",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Buttons under the message: \"Try again\", \"Go to billing\".",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "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"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<AlertSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "The message. `children` works too, and is the better place for links.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "hidden",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Replace the variant's glyph, or pass `false` for none.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<AlertLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onDismiss",
+      "type": "function",
+      "signature": "(() => void) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Show a close button. The alert does not hide itself; remove it in the handler.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLDivElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "md",
+        "sm"
+      ],
+      "typeText": "AlertSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md`. `sm` drops the title to one line of text.",
+      "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": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "danger",
+        "info",
+        "neutral",
+        "success",
+        "warning"
+      ],
+      "typeText": "AlertVariant | undefined",
+      "required": false,
+      "default": "info",
+      "origin": "derived",
+      "description": "Default `info`.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "HTMLAttributes<HTMLDivElement>",
+      "omitted": [
+        "role",
+        "title"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [
+    {
+      "name": "onDismiss",
+      "signature": "(() => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "icon",
+    "content",
+    "title",
+    "description",
+    "actions",
+    "dismiss"
+  ],
+  "states": [
+    {
+      "attr": "data-size",
+      "values": [
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "danger",
+        "neutral",
+        "success",
+        "warning"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 19,
+    "propsDescribed": 6,
+    "describedPct": 32,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/alert/react/Alert.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import {
+  useMemo,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { liveness } from "../core/live";
+import type { AlertLocaleText, AlertSize, AlertVariant } from "../core/types";
+import { VARIANT_ICONS, XIcon } from "./icons";
+import { defaultAlertText } from "./locale";
+import { cx, type AlertSlot } from "./props";
+
+export interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, "title" | "role"> {
+  /** Default `info`. */
+  variant?: AlertVariant;
+  /** Default `md`. `sm` drops the title to one line of text. */
+  size?: AlertSize;
+  title?: ReactNode;
+  /** The message. `children` works too, and is the better place for links. */
+  description?: ReactNode;
+  children?: ReactNode;
+  /** Replace the variant's glyph, or pass `false` for none. */
+  icon?: ReactNode | false;
+  /** Buttons under the message: "Try again", "Go to billing". */
+  actions?: ReactNode;
+  /** Show a close button. The alert does not hide itself; remove it in the handler. */
+  onDismiss?(): void;
+  className?: string;
+  classNames?: Partial<Record<AlertSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<AlertLocaleText>;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * A message that stays in the page: a trial ending, a read-only record, the
+ * summary above a form that failed validation.
+ *
+ * It is the third of three ways to say something, and the only one that is
+ * neither interrupting nor temporary. Use a **Dialog** when the message needs a
+ * decision before anything else can happen, a **Toast** to confirm something
+ * that has already happened, and an Alert for the state a page or section is
+ * in.
+ */
+export function Alert(props: AlertProps) {
+  const {
+    ref,
+    variant = "info",
+    size = "md",
+    title,
+    description,
+    children,
+    icon,
+    actions,
+    onDismiss,
+    className,
+    classNames,
+    style,
+    localeText,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultAlertText, ...localeText }), [localeText]);
+  const { role, live } = liveness(variant);
+  const Glyph = VARIANT_ICONS[variant];
+
+  return (
+    <div
+      {...rest}
+      ref={ref}
+      // Only what appears after the page has loaded is announced; a banner that
+      // was there from the start is read in its turn, like any other text.
+      role={role}
+      aria-live={live}
+      className={cx("al-root", classNames?.root, className)}
+      style={style}
+      data-variant={variant}
+      data-size={size}
+    >
+      {icon !== false && (
+        <span className={cx("al-icon", classNames?.icon)} aria-hidden="true">
+          {icon ?? <Glyph />}
+        </span>
+      )}
+
+      <div className={cx("al-content", classNames?.content)}>
+        {title && <p className={cx("al-title", classNames?.title)}>{title}</p>}
+        {(description || children) && (
+          <div className={cx("al-description", classNames?.description)}>
+            {description}
+            {children}
+          </div>
+        )}
+        {actions && <div className={cx("al-actions", classNames?.actions)}>{actions}</div>}
+      </div>
+
+      {onDismiss && (
+        <button
+          type="button"
+          className={cx("al-dismiss", classNames?.dismiss)}
+          aria-label={text.dismiss}
+          title={text.dismiss}
+          onClick={onDismiss}
+        >
+          <XIcon />
+        </button>
+      )}
+    </div>
+  );
+}

package/source/components/alert/react/icons.tsx

@@ -0,0 +1,21 @@
+import {
+  AlertCircleIcon,
+  InfoIcon,
+  SuccessIcon,
+  WarningIcon,
+  XIcon as SharedX,
+  type IconProps,
+} from "../../shared/react/icons";
+import type { AlertVariant } from "../core/types";
+
+/** 14px, to sit in the corner without pulling the eye from the message. */
+export const XIcon = (p: IconProps) => <SharedX width={14} height={14} {...p} />;
+
+/** The glyph each variant carries, so colour is never the only signal. */
+export const VARIANT_ICONS: Record<AlertVariant, (props: IconProps) => React.JSX.Element> = {
+  info: InfoIcon,
+  success: SuccessIcon,
+  warning: WarningIcon,
+  danger: AlertCircleIcon,
+  neutral: InfoIcon,
+};

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

@@ -0,0 +1,5 @@
+import type { AlertLocaleText } from "../core/types";
+
+export const defaultAlertText: AlertLocaleText = {
+  dismiss: "Dismiss",
+};

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

@@ -0,0 +1,11 @@
+export type AlertSlot =
+  | "root"
+  | "icon"
+  | "content"
+  | "title"
+  | "description"
+  | "actions"
+  | "dismiss";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/alert/styles.css

@@ -0,0 +1,154 @@
+/*
+ * Alert styles.
+ *
+ * A banner that sits in the page, tinted by variant. Tokens read the shared
+ * --gbs-* variables when they are set on an ancestor (set them on :root to
+ * theme every component at once). Rules are unlayered: they beat a framework
+ * reset on specificity, and lose to anything you pass through `className`.
+ * With Tailwind v4, import this file after the framework and inside its
+ * components layer - see the README.
+ */
+
+.al-root {
+  --al-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --al-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --al-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --al-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --al-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+  --al-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --al-info: var(--gbs-info, var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa))));
+  --al-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+  --al-warning: var(--gbs-warning, light-dark(#b45309, #fbbf24));
+  --al-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --al-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --al-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --al-accent: var(--al-info);
+  --al-px: 14px;
+  --al-py: 12px;
+
+  color-scheme: inherit;
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  min-width: 0;
+  padding: var(--al-py) var(--al-px);
+  /* The bar carries the variant at a glance; the tint alone is too faint to
+     read as a signal, and colour is never the only one — there is a glyph. */
+  border: 1px solid var(--al-border);
+  border-inline-start: 3px solid var(--al-accent);
+  border-radius: var(--al-radius);
+  background: color-mix(in oklab, var(--al-accent) 7%, var(--al-bg));
+  font-size: var(--al-font-size);
+  line-height: 1.5;
+  color: var(--al-fg);
+  text-wrap: pretty;
+}
+
+:where(.dark, [data-theme="dark"]) .al-root {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .al-root {
+  color-scheme: light;
+}
+
+:where(.al-root) *,
+:where(.al-root) *::before,
+:where(.al-root) *::after {
+  box-sizing: border-box;
+}
+
+.al-root[data-variant="success"] {
+  --al-accent: var(--al-success);
+}
+.al-root[data-variant="warning"] {
+  --al-accent: var(--al-warning);
+}
+.al-root[data-variant="danger"] {
+  --al-accent: var(--al-danger);
+}
+.al-root[data-variant="neutral"] {
+  --al-accent: var(--al-muted);
+}
+
+.al-root[data-size="sm"] {
+  --al-px: 10px;
+  --al-py: 8px;
+  --al-font-size: 12px;
+  gap: 8px;
+}
+
+.al-icon {
+  display: inline-flex;
+  flex: none;
+  /* Optically centred on the first line of text rather than its box. */
+  margin-top: 1px;
+  color: var(--al-accent);
+}
+.al-icon > svg {
+  width: 16px;
+  height: 16px;
+}
+.al-root[data-size="sm"] .al-icon > svg {
+  width: 14px;
+  height: 14px;
+}
+
+.al-content {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+.al-title {
+  margin: 0;
+  font-weight: 600;
+}
+.al-description {
+  margin: 0;
+  /* Not muted: this is the message, not a hint about one. */
+  color: inherit;
+}
+.al-description a {
+  color: var(--al-accent);
+  text-underline-offset: 2px;
+}
+.al-actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin-top: 8px;
+}
+
+.al-dismiss {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  margin: -2px -4px 0 0;
+  padding: 0;
+  border: 0;
+  border-radius: 4px;
+  background: none;
+  color: var(--al-muted);
+  cursor: pointer;
+}
+.al-dismiss:hover {
+  background: var(--al-hover);
+  color: var(--al-fg);
+}
+.al-dismiss:focus-visible {
+  outline: 2px solid var(--al-focus);
+  outline-offset: 1px;
+}
+
+@media (forced-colors: active) {
+  .al-root {
+    border: 1px solid CanvasText;
+    border-inline-start-width: 3px;
+  }
+}

package/source/components/avatar/core/identity.ts

@@ -0,0 +1,103 @@
+/**
+ * Turning a name into the two things an avatar needs when there is no picture:
+ * a couple of letters, and a colour that is always the same for that person.
+ *
+ * Both are harder than they look, and both are wrong in a way that is hard to
+ * notice from an English-speaking desk — which is why they are here, pure and
+ * under test, rather than inline in the component.
+ */
+
+/**
+ * Names are split on whitespace — `\s` covers the no-break space a copied name
+ * often carries — and on the punctuation that joins parts of one.
+ */
+const SEPARATORS = /[\s._\-–—/\\|,]+/u;
+
+/**
+ * Letters from a name: two for a name with parts, one otherwise.
+ *
+ * `"Ada Lovelace"` gives `AL`, `"ada"` gives `A`, `"ada@example.com"` gives
+ * `A` — an email is not a name, so only the part before the `@` is looked at
+ * and never the domain.
+ *
+ * Two deliberate decisions:
+ *
+ * Characters are taken with `Intl.Segmenter` where it exists, so a name
+ * beginning with an emoji, a surrogate pair or a letter carrying a combining
+ * mark yields that whole character rather than half of it — `slice(0, 1)` on a
+ * string is a byte operation wearing a costume.
+ *
+ * Scripts without letter case are left alone: uppercasing is meaningless for
+ * CJK and can change the character. A Japanese name gives its first character,
+ * not a mangled one.
+ */
+export function initials(name: string, max = 2): string {
+  const source = name.trim().split("@")[0] ?? "";
+  if (source === "") return "";
+
+  const parts = source.split(SEPARATORS).filter(Boolean);
+  if (parts.length === 0) return "";
+
+  // One part is a single name or a handle: one letter is enough, and taking
+  // two from "Madonna" gives "MA", which looks like a mistake.
+  const chosen = parts.length === 1 ? [parts[0]] : [parts[0], parts[parts.length - 1]];
+
+  return chosen
+    .slice(0, max)
+    .map((part) => firstCharacter(part))
+    .join("");
+}
+
+function firstCharacter(part: string): string {
+  const character = segmentFirst(part);
+  // `toLocaleUpperCase` on a script with no case returns it unchanged, which is
+  // the behaviour we want; it is the two-character mappings (ß → SS) that have
+  // to be cut back to one.
+  const upper = character.toLocaleUpperCase();
+  return upper.length > character.length ? character : upper;
+}
+
+let segmenter: Intl.Segmenter | null | undefined;
+
+function segmentFirst(text: string): string {
+  if (segmenter === undefined) {
+    segmenter = typeof Intl !== "undefined" && "Segmenter" in Intl ? new Intl.Segmenter() : null;
+  }
+  if (segmenter) {
+    for (const { segment } of segmenter.segment(text)) return segment;
+    return "";
+  }
+  // Without Segmenter, code points at least keep surrogate pairs whole.
+  return Array.from(text)[0] ?? "";
+}
+
+/**
+ * A stable index into a palette, from any string.
+ *
+ * The same person keeps the same colour on every page and in every session,
+ * without anything being stored, because the hash is a pure function of their
+ * name. FNV-1a: small, well spread for short strings, and not a security
+ * decision — nothing here is a secret.
+ */
+export function colorIndex(seed: string, count: number): number {
+  if (count <= 0) return 0;
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < seed.length; index++) {
+    hash ^= seed.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return Math.abs(hash) % count;
+}
+
+/**
+ * How an avatar group splits: the faces shown, and how many are left over.
+ *
+ * The overflow counter takes one of the slots, so showing "+2" out of five
+ * faces with `max: 3` means two faces and a counter, not three and a counter.
+ */
+export function splitGroup<T>(items: readonly T[], max: number): { shown: T[]; overflow: number } {
+  if (max <= 0) return { shown: [], overflow: items.length };
+  if (items.length <= max) return { shown: [...items], overflow: 0 };
+  const shown = items.slice(0, max - 1);
+  return { shown, overflow: items.length - shown.length };
+}

package/source/components/avatar/core/index.ts

@@ -0,0 +1,2 @@
+export { colorIndex, initials, splitGroup } from "./identity";
+export type * from "./types";

package/source/components/avatar/core/types.ts

@@ -0,0 +1,12 @@
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+export type AvatarShape = "circle" | "square";
+
+/** Who is on the other side of a presence dot. */
+export type AvatarStatus = "online" | "away" | "busy" | "offline";
+
+export interface AvatarLocaleText {
+  /** The overflow bubble in a group. */
+  more(count: number): string;
+  status: Record<AvatarStatus, string>;
+}

package/source/components/avatar/index.ts

@@ -0,0 +1,7 @@
+export { Avatar } from "./react/Avatar";
+export type { AvatarProps } from "./react/Avatar";
+export { AvatarGroup } from "./react/AvatarGroup";
+export type { AvatarGroupProps } from "./react/AvatarGroup";
+export { defaultAvatarText } from "./react/locale";
+export type { AvatarGroupSlot, AvatarSlot } from "./react/props";
+export * from "./core";