premium-ds 0.1.0

package/src/components/alert/Alert.tsx

@@ -0,0 +1,118 @@
+'use client';
+
+/* Alert - the persistent, in-flow status message (banner is a paint modifier). */
+
+import * as React from 'react';
+import { motion, AnimatePresence } from 'motion/react';
+import { UIMotion } from '../../tokens/motion-tokens';
+import { Icon, type IconName } from '../icon/Icon';
+import { IconSlot } from '../icon/IconSlot';
+
+export type AlertTone = 'info' | 'success' | 'warning' | 'danger';
+
+export interface AlertAction {
+  /** Sentence-case label, e.g. "Update billing". */
+  label: string;
+  onClick?: () => void;
+}
+
+export interface AlertProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** Status of the message; info/success are polite, warning/danger assertive. Default 'info'. */
+  tone?: AlertTone;
+  /** The message - sentence case, ideally one line. */
+  title: React.ReactNode;
+  /** Optional description; stays neutral - tone marks the message, not the prose. */
+  children?: React.ReactNode;
+  /** One action max, rendered as the system secondary small button. */
+  action?: AlertAction;
+  /** Renders the always-visible close button. Uncontrolled unless `open` is given. */
+  dismissible?: boolean;
+  /** Fires on dismiss. With `open` set, the parent owns hiding the alert. */
+  onDismiss?: () => void;
+  /** Controlled visibility; omit for uncontrolled. Exit eases shut (height collapse). */
+  open?: boolean;
+  /** App-level strip: square corners, hairline below only. Paint modifier. */
+  banner?: boolean;
+  /** Override the tone glyph; pass null to render no glyph. */
+  icon?: React.ReactNode | null;
+}
+
+const { t } = UIMotion;
+
+const TONE_GLYPH: Record<AlertTone, IconName> = {
+  info: 'info',
+  success: 'check-circle',
+  warning: 'warning',
+  danger: 'warning-circle',
+};
+const TONE_ROLE: Record<AlertTone, string> = {
+  info: 'status',
+  success: 'status',
+  warning: 'alert',
+  danger: 'alert',
+};
+
+export function Alert({
+  tone = 'info',
+  title,
+  children = null,
+  action = null,
+  dismissible = false,
+  onDismiss,
+  open,
+  banner = false,
+  icon,
+  className = '',
+  ...rest
+}: AlertProps) {
+  const [selfOpen, setSelfOpen] = React.useState(true);
+  const isOpen = open === undefined ? selfOpen : open;
+
+  const dismiss = () => {
+    if (open === undefined) setSelfOpen(false);
+    if (onDismiss) onDismiss();
+  };
+
+  const classes = ['alert', banner ? 'alert--banner' : '', className].filter(Boolean).join(' ');
+
+  return (
+    <AnimatePresence initial={false}>
+      {isOpen && (
+        <motion.div
+          key="alert-shell" /* explicit key - AnimatePresence strands un-keyed conditional children */
+          className="alert-shell"
+          initial={{ height: 0, opacity: 0 }}
+          animate={{ height: 'auto', opacity: 1 }}
+          exit={{ height: 0, opacity: 0, transition: { height: t.layout, opacity: t.exit } }}
+          transition={{ height: t.layout, opacity: t.enter }}
+        >
+          <div className={classes} data-tone={tone} role={TONE_ROLE[tone] || 'status'} {...rest}>
+            {icon === null ? null : (
+              <span className="alert__icon" aria-hidden="true">
+                {icon !== undefined ? (
+                  <IconSlot size="md">{icon}</IconSlot>
+                ) : (
+                  <Icon name={TONE_GLYPH[tone] || 'info'} size="md" />
+                )}
+              </span>
+            )}
+            <div className="alert__body">
+              <p className="alert__title">{title}</p>
+              {children != null && <p className="alert__desc">{children}</p>}
+            </div>
+            {action && (
+              <button type="button" className="btn btn--sm alert__action" onClick={action.onClick}>
+                {action.label}
+              </button>
+            )}
+            {dismissible && (
+              <button type="button" className="alert__close" aria-label="Dismiss" onClick={dismiss}>
+                <Icon name="close" size="sm" />
+              </button>
+            )}
+          </div>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}

package/src/components/alert/alert.css

@@ -0,0 +1,136 @@
+/* alert.css - the persistent in-flow status message: a lit tinted pane per tone. */
+
+.alert-shell {
+  overflow: hidden;
+}
+
+.alert {
+  /* tone hooks - repointed by [data-tone] below; info is the default */
+  --alert-hue: var(--info);
+  --alert-fg: var(--info-text);
+  --alert-bg: var(--info-subtle);
+  --alert-wash: var(--accent-wash); /* info's wash = accent (teal) */
+
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-3) var(--space-4);
+  /* the lit pane: top-light gradient over the tint + 1px inner highlight (Button's lighting model) */
+  background: linear-gradient(
+    180deg,
+    color-mix(in oklab, var(--bg-surface) 45%, var(--alert-bg)),
+    var(--alert-bg)
+  );
+  border: var(--border-hairline) solid color-mix(in oklab, var(--alert-hue) 30%, transparent);
+  border-radius: var(--radius-lg);
+  box-shadow: inset 0 1px 0 0 rgb(255 255 255 / 0.55);
+}
+
+.alert[data-tone='success'] {
+  --alert-hue: var(--success);
+  --alert-fg: var(--success-text);
+  --alert-bg: var(--success-subtle);
+  --alert-wash: var(--success-wash);
+}
+.alert[data-tone='warning'] {
+  --alert-hue: var(--warning);
+  --alert-fg: var(--warning-text);
+  --alert-bg: var(--warning-subtle);
+  --alert-wash: var(--warning-wash);
+}
+.alert[data-tone='danger'] {
+  --alert-hue: var(--danger);
+  --alert-fg: var(--danger-text);
+  --alert-bg: var(--danger-subtle);
+  --alert-wash: var(--danger-wash);
+}
+
+/* with a description: glyph rides the title line, controls stay centered */
+.alert:has(.alert__desc) {
+  align-items: flex-start;
+}
+.alert:has(.alert__desc) .alert__action,
+.alert:has(.alert__desc) .alert__close {
+  align-self: center;
+}
+
+.alert--banner {
+  border-radius: 0;
+  border-block-start: 0;
+  border-inline: 0;
+  padding-inline: var(--space-6);
+}
+
+/* Glyph - one --leading-body tall so it centers on the title line. */
+.alert__icon {
+  flex: none;
+  display: grid;
+  place-items: center;
+  height: var(--leading-body);
+  color: var(--alert-hue);
+}
+
+.alert__body {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.alert__title {
+  margin: 0;
+  font: var(--type-label);
+  color: var(--alert-fg);
+  text-wrap: pretty;
+}
+.alert__desc {
+  margin: var(--space-1) 0 0;
+  font: var(--type-caption);
+  color: color-mix(in oklab, var(--alert-fg) 56%, var(--text-body));
+  text-wrap: pretty;
+}
+
+/* Action - the system .btn .btn--sm re-skinned to the pane's tone (alert-local chrome, not a global Button variant). */
+.alert__action {
+  flex: none;
+  color: var(--alert-fg);
+  background: transparent;
+}
+.alert__action:hover:not(:disabled) {
+  color: var(--alert-fg);
+  background: var(--alert-wash);
+}
+.alert__action:active:not(:disabled) {
+  background: color-mix(in oklab, var(--alert-hue) 16%, transparent);
+  transform: translateY(var(--space-px));
+}
+.alert[data-tone='danger'] .alert__action {
+  --btn-ring: var(--ring-danger);
+}
+
+/* Dismiss - always visible (alerts persist; no hover-reveal like toast). */
+.alert__close {
+  flex: none;
+  appearance: none;
+  display: grid;
+  place-items: center;
+  width: var(--space-6);
+  height: var(--space-6);
+  margin: 0;
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: color-mix(in oklab, var(--alert-fg) 64%, transparent);
+  cursor: pointer;
+  transition: var(--transition-control);
+}
+.alert__close:hover {
+  background: color-mix(in oklab, var(--alert-fg) 9%, transparent);
+  color: var(--alert-fg);
+}
+.alert__close:active {
+  background: color-mix(in oklab, var(--alert-fg) 14%, transparent);
+}
+.alert__close:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}

package/src/components/avatar/Avatar.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+// Avatar - identity mark; content priority: image - icon - initials - silhouette.
+
+import * as React from 'react';
+
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type AvatarShape = 'circle' | 'square';
+export type AvatarStatus = 'online' | 'away' | 'busy' | 'offline';
+export type AvatarPaletteIndex = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Image URL. Falls back to initials / icon / silhouette if absent or fails. */
+  src?: string | null;
+  /** Display name - drives initials generation, palette hash, and aria-label. */
+  name?: string | null;
+  /** Content override - any React node (e.g. <Icon name="globe" />). */
+  icon?: React.ReactNode | null;
+  /** 'circle' for people; 'square' for channels / brand pages. Default 'circle'. */
+  shape?: AvatarShape;
+  /** Size step. Default 'md' (32 px). */
+  size?: AvatarSize;
+  /** Presence indicator dot at bottom-right. Default null (hidden). */
+  status?: AvatarStatus | null;
+  /** Override identity slot 1-6 (blue - violet - plum - rose - clay - moss); auto from name hash when null, neutral when anonymous. */
+  paletteIndex?: AvatarPaletteIndex | null;
+}
+
+const _PALETTE_SLOTS = 6;
+
+function _hash(str: string) {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+  return (Math.abs(h) % _PALETTE_SLOTS) + 1;
+}
+
+function _initials(name: string | null, max: number) {
+  if (!name) return '';
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return '';
+  if (parts.length === 1 || max === 1) return parts[0][0].toUpperCase();
+  return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+}
+
+function _Silhouette() {
+  return (
+    <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+      <circle cx="12" cy="8.5" r="3.8" fill="currentColor" />
+      <path d="M4 20.5C4 16.1 7.6 13 12 13s8 3.1 8 7.5" fill="currentColor" opacity="0.65" />
+    </svg>
+  );
+}
+
+export function Avatar({
+  src = null,
+  name = null,
+  icon = null,
+  shape = 'circle',
+  size = 'md',
+  status = null,
+  paletteIndex = null,
+  className = '',
+  style = {},
+  ...rest
+}: AvatarProps) {
+  const [imgError, setImgError] = React.useState(false);
+  const showImg = Boolean(src) && !imgError;
+
+  const maxInits = size === 'xs' ? 1 : 2;
+  const inits = _initials(name, maxInits);
+  const slot = paletteIndex ?? (name ? _hash(name) : null);
+
+  const classes = [
+    'avatar',
+    size !== 'md' ? `avatar--${size}` : '',
+    shape === 'square' ? 'avatar--square' : '',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <span
+      className={classes}
+      role={name ? 'img' : undefined}
+      aria-label={name || undefined}
+      data-palette={!showImg && slot != null ? slot : undefined}
+      style={style}
+      {...rest}
+    >
+      <span className="avatar__face">
+        {showImg && (
+          <img
+            className="avatar__img"
+            src={src}
+            alt={name || ''}
+            onError={() => setImgError(true)}
+            draggable={false}
+          />
+        )}
+        {!showImg && icon && (
+          <span className="avatar__icon" aria-hidden="true">
+            {icon}
+          </span>
+        )}
+        {!showImg && !icon && inits && (
+          <span className="avatar__initials" aria-hidden="true">
+            {inits}
+          </span>
+        )}
+        {!showImg && !icon && !inits && (
+          <span className="avatar__icon" aria-hidden="true">
+            <_Silhouette />
+          </span>
+        )}
+      </span>
+
+      {status && (
+        <span
+          className={`avatar__status avatar__status--${status}`}
+          role="img"
+          aria-label={status}
+          title={status}
+        />
+      )}
+    </span>
+  );
+}

package/src/components/avatar/AvatarGroup.tsx

@@ -0,0 +1,50 @@
+'use client';
+
+// AvatarGroup - stacks Avatars with overlap + a "+N" overflow chip; CSS drives the hover-spread.
+
+import * as React from 'react';
+import type { AvatarSize } from './Avatar';
+
+export interface AvatarGroupProps extends React.HTMLAttributes<HTMLSpanElement> {
+  children: React.ReactNode;
+  /** Max visible avatars before "+N" overflow chip. Default 5. */
+  max?: number;
+  /** Uniform size applied to all children. Default 'md'. */
+  size?: AvatarSize;
+}
+
+export function AvatarGroup({
+  children,
+  max = 5,
+  size = 'md',
+  className = '',
+  ...rest
+}: AvatarGroupProps) {
+  const items = React.Children.toArray(children);
+  const visible = max > 0 ? items.slice(0, max) : items;
+  const overflow = items.length - visible.length;
+
+  return (
+    <span className={['avatar-group', className].filter(Boolean).join(' ')} {...rest}>
+      {visible.map((child, i) =>
+        React.isValidElement(child)
+          ? React.cloneElement(child as React.ReactElement<{ size?: AvatarSize }>, {
+              size,
+              key: child.key ?? i,
+            })
+          : child,
+      )}
+      {overflow > 0 && (
+        <span
+          className={`avatar avatar--${size} avatar--overflow`}
+          role="img"
+          aria-label={`${overflow} more`}
+        >
+          <span className="avatar__face">
+            <span className="avatar__initials">+{overflow}</span>
+          </span>
+        </span>
+      )}
+    </span>
+  );
+}

package/src/components/avatar/avatar.css

@@ -0,0 +1,200 @@
+/* Avatar (image - initials - icon) + AvatarGroup - face/status structure, token sizes, 6 identity slots. */
+
+.avatar {
+  --avatar-size: 2rem;
+  --avatar-bg: var(--bg-muted);
+  --avatar-fg: var(--text-muted);
+  /* --avatar-ring: injected by .avatar-group, cascades to .avatar__face */
+
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  vertical-align: middle;
+  width: var(--avatar-size);
+  height: var(--avatar-size);
+}
+
+.avatar__face {
+  width: 100%;
+  height: 100%;
+  border-radius: var(--radius-full);
+  overflow: hidden;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  background: var(--avatar-bg);
+  color: var(--avatar-fg);
+
+  /* sheen from top, shade from bottom over the slot tint; an image child paints over both (section B3 gradient exception) */
+  background:
+    linear-gradient(to bottom, var(--avatar-sheen), transparent 55%),
+    linear-gradient(to top, var(--avatar-shade), transparent 45%), var(--avatar-bg);
+
+  /* Crisp 1px edge-catch + optional group separator ring via cascade */
+  box-shadow:
+    inset 0 1px 0 0 oklch(1 0 0 / 0.5),
+    var(--avatar-ring, none);
+
+  /* keyline keyed to the slot's own hue (fg at low alpha), not uniform black; outline paints above children so it rings photos too */
+  outline: var(--border-hairline) solid color-mix(in oklch, var(--avatar-fg) 18%, transparent);
+  outline-offset: -1px;
+
+  transition: box-shadow var(--duration-fast) var(--ease-standard);
+}
+
+.avatar__img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* lettermark, ratio-sized (section A7 exception); text-box trim = true optical centering; negative margin returns the trailing --tracking-caps so the pair stays centered */
+.avatar__initials {
+  font-family: var(--font-sans);
+  font-weight: var(--weight-semibold);
+  font-size: calc(var(--avatar-size) * 0.42);
+  line-height: 1;
+  text-box: trim-both cap alphabetic;
+  letter-spacing: var(--tracking-caps);
+  margin-right: calc(-1 * var(--tracking-caps));
+  text-transform: uppercase;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.avatar__icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 56%;
+  height: 56%;
+  opacity: 0.5;
+}
+.avatar__icon svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+.avatar--xs {
+  --avatar-size: 1.25rem;
+}
+.avatar--sm {
+  --avatar-size: 1.5rem;
+}
+.avatar--lg {
+  --avatar-size: 2.5rem;
+}
+.avatar--xl {
+  --avatar-size: 3rem;
+}
+
+/* square - radius scales with size (concentric nesting) */
+.avatar--square .avatar__face {
+  border-radius: var(--radius-md);
+}
+
+.avatar--square.avatar--lg .avatar__face,
+.avatar--square.avatar--xl .avatar__face {
+  border-radius: var(--radius-lg);
+}
+
+/* data-palette 1-6: identity slots (tokens/avatar.css); no attr = neutral; identity colouring, never status */
+
+.avatar[data-palette='1'] {
+  --avatar-bg: var(--avatar-1-bg);
+  --avatar-fg: var(--avatar-1-fg);
+}
+.avatar[data-palette='2'] {
+  --avatar-bg: var(--avatar-2-bg);
+  --avatar-fg: var(--avatar-2-fg);
+}
+.avatar[data-palette='3'] {
+  --avatar-bg: var(--avatar-3-bg);
+  --avatar-fg: var(--avatar-3-fg);
+}
+.avatar[data-palette='4'] {
+  --avatar-bg: var(--avatar-4-bg);
+  --avatar-fg: var(--avatar-4-fg);
+}
+.avatar[data-palette='5'] {
+  --avatar-bg: var(--avatar-5-bg);
+  --avatar-fg: var(--avatar-5-fg);
+}
+.avatar[data-palette='6'] {
+  --avatar-bg: var(--avatar-6-bg);
+  --avatar-fg: var(--avatar-6-fg);
+}
+
+/* status dot lives outside .avatar__face (which clips) so it's never cut; ~27% of size, min 6px */
+
+.avatar__status {
+  position: absolute;
+  bottom: 0;
+  right: 0;
+
+  width: calc(var(--avatar-size) * 0.275);
+  height: calc(var(--avatar-size) * 0.275);
+  min-width: 6px;
+  min-height: 6px;
+
+  border-radius: var(--radius-full);
+  box-shadow: 0 0 0 2px var(--bg-surface);
+  transition: background-color var(--duration-fast) var(--ease-standard);
+}
+
+.avatar__status--online {
+  background: var(--success);
+}
+.avatar__status--away {
+  background: var(--warning);
+}
+.avatar__status--busy {
+  background: var(--danger);
+}
+.avatar__status--offline {
+  background: var(--border-strong);
+}
+
+.avatar-group {
+  display: inline-flex;
+  align-items: center;
+}
+
+/* inject --avatar-ring on group children - cascades to .avatar__face */
+.avatar-group > .avatar {
+  --avatar-ring: 0 0 0 2px var(--bg-surface);
+}
+
+.avatar-group > .avatar + .avatar {
+  margin-left: calc(var(--avatar-size) * -0.3);
+  transition: margin-left var(--duration-base) var(--ease-entrance);
+}
+
+.avatar-group:hover > .avatar + .avatar {
+  margin-left: var(--space-1);
+}
+
+/* "+N" chip - mono numerals, tracking off (mono is already spaced), smaller ratio to fit "+12" */
+.avatar--overflow .avatar__initials {
+  font-family: var(--font-mono);
+  font-variant-numeric: tabular-nums;
+  font-size: calc(var(--avatar-size) * 0.36);
+  letter-spacing: var(--tracking-normal);
+  margin-right: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .avatar__face {
+    transition: none;
+  }
+  .avatar__status {
+    transition: none;
+  }
+  .avatar-group > .avatar + .avatar {
+    transition: none;
+  }
+}

package/src/components/badge/Badge.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+// Base badge chip - glass surface by default; the outline variant is flat (no glass classes).
+
+import type { HTMLAttributes, ReactNode } from 'react';
+
+export type BadgeTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+
+export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+  /** Status hue. @default 'neutral' */
+  tone?: BadgeTone;
+  /** Surface. @default 'glass' */
+  variant?: 'glass' | 'outline';
+  /** @default 'md' */
+  size?: 'sm' | 'md';
+  /** Leading status dot. */
+  dot?: boolean;
+  /** Dot pulses (implies dot) - for in-progress status. */
+  live?: boolean;
+  /** Fully-rounded shape. */
+  pill?: boolean;
+  /** Optional leading <Icon> (overrides dot if both set). */
+  icon?: ReactNode;
+}
+
+export function Badge({
+  tone = 'neutral',
+  variant = 'glass',
+  size = 'md',
+  dot = false,
+  live = false,
+  pill = false,
+  icon = null,
+  className = '',
+  children,
+  ...rest
+}: BadgeProps) {
+  const isGlass = variant !== 'outline';
+  const classes = [
+    isGlass ? 'glass glass--interactive' : '',
+    'badge',
+    `badge--${tone}`,
+    variant === 'outline' ? 'badge--outline' : '',
+    size !== 'md' ? `badge--${size}` : '',
+    pill ? 'badge--pill' : '',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const showDot = (dot || live) && !icon;
+
+  return (
+    <span className={classes} {...rest}>
+      {showDot ? (
+        <span className={`badge__dot${live ? ' badge__dot--live' : ''}`} aria-hidden="true" />
+      ) : null}
+      {icon ? (
+        <span className="badge__icon" aria-hidden="true">
+          {icon}
+        </span>
+      ) : null}
+      <span className="badge__label">{children}</span>
+    </span>
+  );
+}