@domicile-desktop/component-library 0.0.0-alpha-f2862631a576

package/README.md

@@ -0,0 +1,76 @@
+# @domicile-desktop/component-library
+
+The shared React UI primitives every Domicile app builds on. Components wrap
+[`@base-ui/react`](https://base-ui.com) where a primitive exists — so focus
+management, keyboard navigation, portals, and validation come from base-ui —
+and add the project's styling and ergonomic API on top. This package also
+owns the design system: the Panda CSS preset (tokens, the shared `control`
+recipe) that every other package extends.
+
+Apps MUST build on these primitives rather than rolling their own buttons,
+inputs, or dialogs from raw HTML. If a primitive is missing, add it here and
+consume it — don't fork. See [/docs/guidelines/STYLING.md](../../docs/guidelines/STYLING.md).
+
+## Exports
+
+| Export | What it is |
+|---|---|
+| `@domicile-desktop/component-library/Button` | Polymorphic button (`<button>` / `<a>`), variants + sizes. |
+| `@domicile-desktop/component-library/Input` | Text input with prefix-icon / clearable / invalid states. |
+| `@domicile-desktop/component-library/Textarea` | Auto-sizing textarea with a resize handle. |
+| `@domicile-desktop/component-library/Field` | Label + control + validation-message wrapper (base-ui Field). |
+| `@domicile-desktop/component-library/Select` | Select / listbox (base-ui Select). |
+| `@domicile-desktop/component-library/Autocomplete` | Text field with a caller-supplied list of suggestions under it (base-ui Autocomplete). The caller does the matching, so the list can rank and can offer a line that matches nothing typed. |
+| `@domicile-desktop/component-library/Tabs` | Tabbed container (base-ui Tabs): config-driven `tabs` array, a sliding active underline, `size` variants, inset focus ring. |
+| `@domicile-desktop/component-library/TabRail` | Vertical rail of tabs with a brand slot, footer, and collapse. |
+| `@domicile-desktop/component-library/Card` | Elevated surface with optional title / footer. |
+| `@domicile-desktop/component-library/ModalDialog` | Modal dialog with flattened `title` / `footer` / `trigger` API. |
+| `@domicile-desktop/component-library/SlideOver` | Edge-anchored drawer (base-ui Dialog). |
+| `@domicile-desktop/component-library/Toaster` | Toasts as a deck in a box's top trailing corner — fans out on hover, swipes away, a countdown along each (base-ui Toast). The caller draws each card. |
+| `@domicile-desktop/component-library/Popover` | Non-modal panel anchored to the control that opened it (base-ui Popover), for detail a control has no room for. |
+| `@domicile-desktop/component-library/Avatar` | Avatar with initials / gradient fallback. |
+| `@domicile-desktop/component-library/Kbd` | Keyboard-shortcut key cap. |
+| `@domicile-desktop/component-library/Screen` | Lays its children over one of the desktop's displays, once per display it selects. |
+| `@domicile-desktop/component-library/DisplayProvider` | The desktop the host described, for the `<Screen>`s below it. |
+| `@domicile-desktop/component-library/display-source` | The `Display` / `DisplaySource` types a `DisplayProvider` is fed. |
+| `@domicile-desktop/component-library/Provider` | base-ui `DirectionProvider` wrapper every app roots its tree in. |
+| `@domicile-desktop/component-library/ThemeProvider` | Theme state (`light` / `dark` / `system`) and the `<html data-theme>` side effect. |
+| `@domicile-desktop/component-library/ThemeSwitch` | The toggle that cycles the theme preference. |
+| `@domicile-desktop/component-library/control-sizes` | The `Size` union / `SIZES` array the sized controls share. |
+| `@domicile-desktop/component-library/spacing` | The rem value of one step on the spacing scale, for runtime math. |
+| `@domicile-desktop/component-library/pandacss-preset` | The `domicilePreset` every package's `panda.config.ts` extends. |
+| `@domicile-desktop/component-library/vite-shell` | `shellBuild({ entry })` — the vite build a shell has to have for Domicile to serve it: a module entry rather than an HTML one, a fixed `shell.js` name, the entry's exports kept (`Shell` is what Domicile calls), and the stylesheet folded into the JavaScript. Each of the four fails quietly if you get it wrong. |
+
+Styling goes through the theme defined in the preset
+(`pandacss-preset.ts`) — `color`, `spacing`, `borderRadius`, etc. — with
+both dark (default) and light (`data-theme="light"`) values. Component
+variants are exposed as explicit props, never a `className` passthrough;
+`data-*` attributes communicate variant/state to CSS.
+
+## Conventions
+
+- Every component has a Storybook story (`*.stories.tsx`) with `argTypes` for
+  every prop.
+- Every component has tests (`*.test.tsx`) using `bun:test` +
+  `@testing-library/react`.
+- Icons come from `@phosphor-icons/react/dist/ssr/<IconName>` (the
+  `*Icon`-suffixed name), never the barrel — see
+  [/docs/guidelines/ICONS.md](../../docs/guidelines/ICONS.md).
+
+The rules for adding or changing a component (directory layout, base-ui
+wrapping, props typing, the `control` recipe, storybook categories, testing)
+live in [`docs/AGENTS.md`](./docs/AGENTS.md) and the topic docs it indexes.
+
+## Scripts
+
+```sh
+bun run start:dev        # Storybook dev server on port 4000
+bun run build:storybook  # build static Storybook into storybook-static/
+bun run start:prod       # serve that build on port 4000
+bun run prepare          # panda codegen (generates styled-system/)
+bun run test:unit        # bun:test + happy-dom
+bun run test:types       # tsc --noEmit
+```
+
+From the repo root, `bun run turbo test --filter @domicile-desktop/component-library`
+runs the type check and the unit tests together.

package/package.json

@@ -0,0 +1,90 @@
+{
+  "dependencies": {
+    "@base-ui/react": "^1.8.0",
+    "@phosphor-icons/react": "^2.1.10"
+  },
+  "description": "React components and the Panda CSS design system that Domicile's shells are built from.",
+  "devDependencies": {
+    "@cprussin/tsconfig": "^5.0.0",
+    "@domicile-desktop/test-support": "0.0.0",
+    "@pandacss/dev": "^1.12.1",
+    "@pandacss/preset-panda": "^1.12.1",
+    "@storybook/addon-docs": "^10.6.0",
+    "@storybook/addon-themes": "^10.6.0",
+    "@storybook/react-vite": "^10.6.0",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "http-server": "^14.1.1",
+    "postcss": "^8.5.28",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "storybook": "^10.6.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.2"
+  },
+  "exports": {
+    "./Autocomplete": "./src/Autocomplete/Autocomplete.tsx",
+    "./Avatar": "./src/Avatar/Avatar.tsx",
+    "./Button": "./src/Button/Button.tsx",
+    "./Card": "./src/Card/Card.tsx",
+    "./control-sizes": "./src/control-sizes.ts",
+    "./DisplayProvider": "./src/Screen/DisplayProvider.tsx",
+    "./display-source": "./src/Screen/display-source.ts",
+    "./Field": "./src/Field/Field.tsx",
+    "./Input": "./src/Input/Input.tsx",
+    "./Kbd": "./src/Kbd/Kbd.tsx",
+    "./ModalDialog": "./src/ModalDialog/ModalDialog.tsx",
+    "./Popover": "./src/Popover/Popover.tsx",
+    "./Provider": "./src/Provider/Provider.tsx",
+    "./pandacss-preset": "./src/pandacss-preset.ts",
+    "./Screen": "./src/Screen/Screen.tsx",
+    "./Select": "./src/Select/Select.tsx",
+    "./SlideOver": "./src/SlideOver/SlideOver.tsx",
+    "./Slider": "./src/Slider/Slider.tsx",
+    "./spacing": "./src/spacing.ts",
+    "./standalone-theme-source": "./src/ThemeSwitch/standalone-theme-source.ts",
+    "./TabRail": "./src/TabRail/TabRail.tsx",
+    "./Tabs": "./src/Tabs/Tabs.tsx",
+    "./Textarea": "./src/Textarea/Textarea.tsx",
+    "./ThemeProvider": "./src/ThemeSwitch/ThemeProvider.tsx",
+    "./ThemeSwitch": "./src/ThemeSwitch/ThemeSwitch.tsx",
+    "./Toaster": "./src/Toaster/Toaster.tsx",
+    "./theme-core": "./src/ThemeSwitch/theme-core.ts",
+    "./theme-source": "./src/ThemeSwitch/theme-source.ts",
+    "./vite-shell": "./src/vite-shell.ts"
+  },
+  "files": [
+    "src/**",
+    "styled-system/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.stories.tsx"
+  ],
+  "license": "MIT",
+  "name": "@domicile-desktop/component-library",
+  "peerDependencies": {
+    "react": "^19.2.8"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/component-library",
+    "type": "git",
+    "url": "git+https://github.com/cprussin/domicile.git"
+  },
+  "scripts": {
+    "build:storybook": "storybook build",
+    "prepare": "panda codegen --silent",
+    "start:dev": "storybook dev -p 4000",
+    "start:prod": "http-server storybook-static -p 4000",
+    "test:types": "tsc --noEmit",
+    "test:unit": "bun test"
+  },
+  "type": "module",
+  "version": "0.0.0-alpha-f2862631a576"
+}

package/src/Autocomplete/Autocomplete.tsx

@@ -0,0 +1,339 @@
+import { Autocomplete as BaseAutocomplete } from "@base-ui/react/autocomplete";
+import type { ReactNode } from "react";
+import { css, cva, cx } from "../../styled-system/css";
+import type { ControlVariant } from "../../styled-system/recipes";
+import { control } from "../../styled-system/recipes";
+import { controlSizingStyle } from "../_control/controlSizingStyle";
+import { focusControlOnMouseDown } from "../_control/focus";
+import { PrefixIconStack } from "../_control/PrefixIconStack";
+import { wrapperBase } from "../_control/wrapperBase";
+import type { ExtendProps } from "../extend-props";
+
+export { SIZES, type Size } from "../control-sizes";
+
+/** One line of the list under the field. */
+export type Suggestion<V> = {
+  /** What the caller gets back when this one is taken. */
+  value: V;
+  /** What the field fills with when this one is highlighted or taken. */
+  text: string;
+  /** The line itself. */
+  label: ReactNode;
+  /** A second, quieter line under it — where the suggestion came from, what it will do. */
+  description?: ReactNode | undefined;
+  /** Drawn at the inline start of the line. */
+  icon?: ReactNode | undefined;
+};
+
+type CommonProps<V> = Partial<ControlVariant> & {
+  /**
+   * Whether the first suggestion highlights as soon as the user types, so
+   * Enter takes it and the field fills with it ahead of the caret.
+   *
+   * What an address bar wants: the line it is already halfway to is the first
+   * one, so Enter means "the obvious thing" without an arrow key first. A
+   * field whose first line is not the obvious thing wants this off, or Enter
+   * takes something the user never looked at.
+   */
+  autoHighlight?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Shown in place of the list when `suggestions` is empty. */
+  emptyMessage?: ReactNode | undefined;
+  onSuggestionTaken?: ((value: V) => void) | undefined;
+  onValueChange?: ((value: string) => void) | undefined;
+  rounded?: boolean | undefined;
+  /**
+   * The lines to offer, already chosen and already in order.
+   *
+   * THE CALLER DOES THE MATCHING. A field that filtered what it was given
+   * could only match on the text it can see, and the interesting lists are the
+   * ones where it cannot: an address bar ranks a host the user visits daily
+   * over one they saw once, and offers a search for what was typed that
+   * matches nothing at all.
+   */
+  suggestions: readonly Suggestion<V>[];
+  /** Controls rendered at the inline end of the field, inside its border. */
+  suffixButtons?: ReactNode | undefined;
+  value?: string | undefined;
+  width?: number | undefined;
+};
+
+type Props<V> = ExtendProps<
+  typeof BaseAutocomplete.Input,
+  CommonProps<V> &
+    // A prefix is either decoration or a control, and never both: the icon
+    // slot takes no pointer — it is what the invalid indicator animates in
+    // and out of — so a button put there could not be pressed. A browser's
+    // site indicator is a control, which is what `prefixButtons` is for.
+    (
+      | { prefixButtons?: undefined; prefixIcon?: ReactNode | undefined }
+      | { prefixButtons: ReactNode; prefixIcon?: undefined }
+    )
+>;
+
+/**
+ * A text field with a list of suggestions under it, wrapping the
+ * `@base-ui/react` Autocomplete primitive.
+ *
+ * Same surface as `Input`: the `control` recipe and the `wrapperBase` state
+ * matrix, so its border, focus ring, hover and invalid styling are the other
+ * form controls' verbatim. What it adds is the list — arrow keys move through
+ * it, the highlighted line fills the field ahead of the caret, and Enter takes
+ * it.
+ *
+ * Highlighting fills the field rather than only marking a line, which is the
+ * behavior of every address bar: what the user would get by pressing Enter is
+ * readable without looking away from where they are typing.
+ */
+export const Autocomplete = <V,>({
+  autoHighlight = false,
+  disabled,
+  emptyMessage,
+  onSuggestionTaken,
+  onValueChange,
+  prefixButtons,
+  prefixIcon,
+  rounded = false,
+  size = "md",
+  suggestions,
+  suffixButtons,
+  value,
+  width,
+  ...inputProps
+}: Props<V>) => (
+  <BaseAutocomplete.Root<Suggestion<V>>
+    autoHighlight={autoHighlight}
+    disabled={disabled}
+    items={suggestions}
+    itemToStringValue={(suggestion) => suggestion.text}
+    // `inline` rather than `list` or `both`: the caller has already chosen
+    // which lines to offer — see `suggestions` — so a second round of matching
+    // inside the field would only throw away the ones it could not see a
+    // reason for.
+    mode="inline"
+    onValueChange={(next) => {
+      onValueChange?.(next);
+    }}
+    value={value}
+  >
+    {/* biome-ignore lint/a11y/noNoninteractiveElementInteractions: focuses the field when the wrapper's padding is clicked; mirrors native <label> behavior without a second label polluting the accessible name */}
+    {/* biome-ignore lint/a11y/noStaticElementInteractions: focuses the field when the wrapper's padding is clicked; mirrors native <label> behavior without a second label polluting the accessible name */}
+    <div
+      className={cx(
+        control({ size }),
+        wrapperBase,
+        wrapperStyles({ rounded, size }),
+      )}
+      onMouseDown={focusControlOnMouseDown}
+      style={controlSizingStyle({ width })}
+    >
+      {prefixButtons === undefined ? (
+        <PrefixIconStack prefixIcon={prefixIcon} size={size} />
+      ) : (
+        <span className={affixStyles}>{prefixButtons}</span>
+      )}
+      <BaseAutocomplete.Input
+        {...inputProps}
+        className={inputStyles}
+        data-control=""
+      />
+      {suffixButtons !== undefined && (
+        <span className={affixStyles}>{suffixButtons}</span>
+      )}
+    </div>
+    <BaseAutocomplete.Portal>
+      <BaseAutocomplete.Positioner
+        align="start"
+        className={positionerStyles}
+        side="bottom"
+        sideOffset={6}
+      >
+        <BaseAutocomplete.Popup className={popupStyles}>
+          <BaseAutocomplete.Empty className={emptyStyles}>
+            {emptyMessage}
+          </BaseAutocomplete.Empty>
+          <BaseAutocomplete.List className={listStyles}>
+            {suggestions.map((suggestion, index) => (
+              <BaseAutocomplete.Item
+                className={itemStyles}
+                index={index}
+                key={index}
+                onClick={() => {
+                  onSuggestionTaken?.(suggestion.value);
+                }}
+                value={suggestion}
+              >
+                {suggestion.icon !== undefined && (
+                  <span className={itemIconStyles}>{suggestion.icon}</span>
+                )}
+                <span className={itemLabelStyles}>{suggestion.label}</span>
+                {suggestion.description !== undefined && (
+                  <span className={itemDescriptionStyles}>
+                    {suggestion.description}
+                  </span>
+                )}
+              </BaseAutocomplete.Item>
+            ))}
+          </BaseAutocomplete.List>
+        </BaseAutocomplete.Popup>
+      </BaseAutocomplete.Positioner>
+    </BaseAutocomplete.Portal>
+  </BaseAutocomplete.Root>
+);
+
+const inputStyles = css({
+  "&::placeholder": { color: "muted" },
+  backgroundColor: "transparent",
+  borderStyle: "none",
+  color: "foreground",
+  cursor: { _disabled: "not-allowed", base: "text" },
+  flexGrow: 1,
+  inlineSize: "100%",
+  minInlineSize: 0,
+  outlineStyle: "none",
+  padding: 0,
+  textOverflow: "ellipsis",
+});
+
+// Both ends of the field, which want the same thing: a row of controls that
+// keeps its size while the text beside it grows, and that inherits the
+// control recipe's per-size gap so it is spaced like the rest of the field.
+const affixStyles = css({
+  alignItems: "center",
+  display: "inline-flex",
+  flexShrink: 0,
+  gap: "inherit",
+});
+
+// The rounded variant inflates inline padding by 1.5 spacing units on top of
+// the `control` recipe's per-size padding (xs: 1.5, sm: 2.5, md: 3, lg: 3.5,
+// xl: 4 — see `CONTROL_PADDING_INLINE` in `control-sizes.ts`), matching
+// Input's `rounded` overrides. Values inlined as literals (not derived from a
+// helper) so Panda's static extractor can emit the corresponding atomic
+// classes — helper return values are opaque to it.
+const wrapperStyles = cva({
+  base: {
+    // Owned here rather than in `wrapperBase` for the reason Input owns it —
+    // see the note at the top of `wrapperBase.ts`.
+    cursor: "text",
+  },
+  compoundVariants: [
+    { css: { paddingInline: 3 }, rounded: true, size: "xs" },
+    { css: { paddingInline: 4 }, rounded: true, size: "sm" },
+    { css: { paddingInline: 4.5 }, rounded: true, size: "md" },
+    { css: { paddingInline: 5 }, rounded: true, size: "lg" },
+    { css: { paddingInline: 5.5 }, rounded: true, size: "xl" },
+    { css: { paddingInline: 7 }, rounded: true, size: "2xl" },
+    { css: { paddingInline: 9 }, rounded: true, size: "3xl" },
+    { css: { paddingInline: 11.5 }, rounded: true, size: "4xl" },
+  ],
+  variants: {
+    rounded: {
+      true: { borderRadius: "full" },
+    },
+    size: {
+      "2xl": {},
+      "3xl": {},
+      "4xl": {},
+      lg: {},
+      md: {},
+      sm: {},
+      xl: {},
+      xs: {},
+    },
+  },
+});
+
+const positionerStyles = css({
+  outlineStyle: "none",
+  zIndex: "modal",
+});
+
+const popupStyles = css({
+  "&[data-ending-style]": {
+    opacity: 0,
+    transform: "scaleY(0.9)",
+    transition:
+      "opacity {durations.fast} {easings.in}, transform {durations.fast} {easings.in}",
+  },
+  // base-ui's own attribute rather than Panda's `_starting`: the browser's
+  // `@starting-style` does not reliably fire for an element that mounts inside
+  // a portal, which leaves the list snapped into place with no animation.
+  "&[data-starting-style]": {
+    opacity: 0,
+    transform: "scaleY(0.9)",
+  },
+  backgroundColor: "card",
+  border: "1px solid {colors.border}",
+  borderRadius: "md",
+  boxShadow: "lifted",
+  display: "flex",
+  flexDirection: "column",
+  // The field's own width, so the list reads as a continuation of it rather
+  // than a panel that happens to be underneath. `--anchor-width` is measured
+  // by base-ui's positioner.
+  inlineSize: "var(--anchor-width)",
+  maxBlockSize: "min(60vh, {spacing.96})",
+  opacity: 1,
+  outlineStyle: "none",
+  overflow: "hidden",
+  paddingBlock: 1,
+  transform: "scaleY(1)",
+  transformOrigin: "top",
+  transition:
+    "opacity {durations.normal} {easings.out}, transform {durations.normal} {easings.out}",
+});
+
+// Stays mounted whether or not the list is empty — base-ui announces the
+// change through it, and a node that is conditionally rendered announces
+// nothing. `:empty` is what hides it when there is nothing to say.
+const emptyStyles = css({
+  "&:empty": { display: "none" },
+  color: "muted",
+  fontSize: "sm",
+  paddingBlock: 2,
+  paddingInline: 3,
+});
+
+const listStyles = css({
+  flexGrow: 1,
+  minBlockSize: 0,
+  overflowY: "auto",
+});
+
+const itemStyles = css({
+  "&[data-highlighted]": {
+    backgroundColor: "color-mix(in oklab, {colors.foreground} 8%, transparent)",
+  },
+  alignItems: "center",
+  color: "foreground",
+  columnGap: 2,
+  cursor: "pointer",
+  display: "grid",
+  fontSize: "sm",
+  // The icon takes what it needs, the label takes the rest, and the
+  // description is pinned at the inline end — which is the shape of every
+  // address bar's list: what you are going to, and why it is being offered.
+  gridTemplateColumns: "auto 1fr auto",
+  outlineStyle: "none",
+  paddingBlock: 1.5,
+  paddingInline: 3,
+});
+
+const itemIconStyles = css({
+  alignItems: "center",
+  color: "muted",
+  display: "inline-flex",
+});
+
+const itemLabelStyles = css({
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+});
+
+const itemDescriptionStyles = css({
+  color: "muted",
+  fontSize: "xs",
+  whiteSpace: "nowrap",
+});

package/src/Avatar/Avatar.tsx

@@ -0,0 +1,124 @@
+import type { ImageLoadingStatus } from "@base-ui/react/avatar";
+import { Avatar as BaseAvatar } from "@base-ui/react/avatar";
+import { useState } from "react";
+import { css, cva } from "../../styled-system/css";
+import { center, circle } from "../../styled-system/patterns";
+import type { ExtendProps } from "../extend-props";
+
+import { getGradient } from "./gradient";
+import { getInitials } from "./initials";
+
+export const AVATAR_SIZES = [
+  "2xs",
+  "xs",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "2xl",
+] as const;
+export type AvatarSize = (typeof AVATAR_SIZES)[number];
+
+type Props = ExtendProps<
+  typeof BaseAvatar.Root,
+  {
+    alt?: string | undefined;
+    children?: undefined;
+    name: string;
+    size?: AvatarSize | undefined;
+    src?: string | undefined;
+  }
+>;
+
+export const Avatar = ({ name, size = "md", src, alt, ...props }: Props) => {
+  const [status, setStatus] = useState<ImageLoadingStatus>("idle");
+
+  const fallbackVisible = src === undefined || status === "error";
+  return (
+    <BaseAvatar.Root {...props} className={rootStyles({ size })}>
+      <span
+        aria-hidden
+        className={skeletonStyles({ loading: status === "loading" })}
+      />
+      {src !== undefined && (
+        // `key={src}` so the Image remounts when `src` changes, re-issuing
+        // `onLoadingStatusChange` from "idle" → "loading" → final. Without
+        // the key, a previously-loaded Image stays mounted and `status`
+        // stays at its prior value through the transition, briefly mismatching
+        // the new src's actual load state.
+        <BaseAvatar.Image
+          alt={alt ?? name}
+          className={imageStyles}
+          key={src}
+          onLoadingStatusChange={setStatus}
+          src={src}
+        />
+      )}
+      <BaseAvatar.Fallback
+        className={fallbackStyles({ visible: fallbackVisible })}
+        style={{ backgroundImage: getGradient(name) }}
+      >
+        {getInitials(name)}
+      </BaseAvatar.Fallback>
+    </BaseAvatar.Root>
+  );
+};
+
+const skeletonStyles = cva({
+  base: {
+    backgroundColor: "skeleton",
+    inset: 0,
+    position: "absolute",
+  },
+  variants: {
+    loading: {
+      false: { animation: "none" },
+      true: { animation: "pulse {durations.pulse} {easings.in-out} infinite" },
+    },
+  },
+});
+
+const imageStyles = css({
+  inset: 0,
+  objectFit: "cover",
+  opacity: { _starting: 0, base: 1 },
+  position: "absolute",
+  transition: "opacity {durations.slowest} {easings.out}",
+});
+
+const fallbackStyles = cva({
+  base: center.raw({
+    inset: 0,
+    position: "absolute",
+    transition: "opacity {durations.slowest} {easings.out}",
+  }),
+  variants: {
+    visible: {
+      false: { opacity: 0 },
+      true: { opacity: 1 },
+    },
+  },
+});
+
+const rootStyles = cva({
+  base: {
+    color: "background",
+    fontWeight: "bold",
+    letterSpacing: "wide",
+    overflow: "hidden",
+    position: "relative",
+    textTransform: "uppercase",
+  },
+  variants: {
+    // biome-ignore assist/source/useSortedKeys: The sort order is useful here
+    size: {
+      "2xs": circle.raw({ fontSize: "xs", size: 6 }),
+      xs: circle.raw({ fontSize: "sm", size: 8 }),
+      sm: circle.raw({ fontSize: "lg", size: 12 }),
+      md: circle.raw({ fontSize: "2xl", size: 16 }),
+      lg: circle.raw({ fontSize: "3xl", size: 20 }),
+      xl: circle.raw({ fontSize: "4xl", size: 24 }),
+      "2xl": circle.raw({ fontSize: "5xl", size: 28 }),
+    },
+  },
+});

package/src/Avatar/gradient.ts

@@ -0,0 +1,17 @@
+export const getGradient = (name: string): string => {
+  const normalized = name.trim().toLowerCase();
+  const seed = hashString(normalized === "" ? "?" : normalized);
+  const hueA = seed % 360;
+  const hueB = (hueA + 30 + ((seed >>> 8) % 60)) % 360;
+  const hueC = (hueA + 180 + ((seed >>> 16) % 40)) % 360;
+  return `linear-gradient(135deg, hsl(${hueA}, 95%, 72%) 0%, hsl(${hueB}, 90%, 68%) 55%, hsl(${hueC}, 95%, 70%) 100%)`;
+};
+
+const hashString = (str: string): number => {
+  let h = 2_166_136_261;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 16_777_619);
+  }
+  return h >>> 0;
+};

package/src/Avatar/initials.ts

@@ -0,0 +1,19 @@
+export const getInitials = (name: string): string => {
+  const parts = name
+    .trim()
+    .split(/\s+/)
+    .filter((part) => part !== "");
+  const first = parts[0];
+  if (first === undefined) {
+    return "?";
+  } else {
+    const last = parts[parts.length - 1];
+    const firstChar = ([...first][0] ?? "").toUpperCase();
+    if (last === undefined || last === first) {
+      return firstChar;
+    } else {
+      const lastChar = ([...last][0] ?? "").toUpperCase();
+      return firstChar + lastChar;
+    }
+  }
+};