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

package/src/Avatar/slowImageDecorator.tsx

@@ -0,0 +1,92 @@
+import type { Decorator } from "@storybook/react-vite";
+import { useEffect, useState } from "react";
+
+/**
+ * Storybook decorator that monkey-patches `window.Image` so the next image
+ * created while a story is mounted defers its load callback by 5 seconds.
+ * Lets the Avatar stories show the loading skeleton long enough to inspect
+ * before the image fades in (or fails). Reverts the patch on unmount.
+ *
+ * The patch is installed during render (via `useState` lazy init) rather
+ * than from `useEffect`, because base-ui's `useImageLoadingStatus` calls
+ * `new window.Image()` from inside `useIsoLayoutEffect` — a *layout* effect
+ * that fires before our decorator's passive `useEffect`. Installing the
+ * patch later would miss the probe Image's construction and the loading
+ * delay would never apply. Uninstall still runs from `useEffect` cleanup,
+ * which is fine because the patch only needs to be removed on unmount.
+ */
+export const slowImageDecorator: Decorator = (Story) => {
+  useState(installSlowImage);
+  useEffect(() => uninstallSlowImage, []);
+  return <Story />;
+};
+
+const SLOW_LOAD_MS = 5000;
+const PATCH_FLAG = "__avatarSlowImageOriginal";
+
+type PatchedWindow = typeof window & { [PATCH_FLAG]?: typeof window.Image };
+
+const installSlowImage = () => {
+  if (typeof window === "undefined") {
+    return;
+  } else {
+    const w = window as PatchedWindow;
+    if (w[PATCH_FLAG] === undefined) {
+      const OriginalImage = window.Image;
+      const srcDescriptor = Object.getOwnPropertyDescriptor(
+        HTMLImageElement.prototype,
+        "src",
+      );
+      const completeDescriptor = Object.getOwnPropertyDescriptor(
+        HTMLImageElement.prototype,
+        "complete",
+      );
+      if (srcDescriptor === undefined || completeDescriptor === undefined) {
+        return;
+      } else {
+        // Must be a `function` (not arrow) because consumers call
+        // `new window.Image(...)` and arrow functions are not constructable.
+        const SlowImage = function (
+          ...args: ConstructorParameters<typeof OriginalImage>
+        ) {
+          const img = new OriginalImage(...args);
+          let pending = false;
+          Object.defineProperty(img, "complete", {
+            configurable: true,
+            get: () =>
+              pending === true ? false : completeDescriptor.get?.call(img),
+          });
+          Object.defineProperty(img, "src", {
+            configurable: true,
+            get: () => srcDescriptor.get?.call(img),
+            set: (value: string) => {
+              pending = true;
+              window.setTimeout(() => {
+                pending = false;
+                srcDescriptor.set?.call(img, value);
+              }, SLOW_LOAD_MS);
+            },
+          });
+          return img;
+        } as unknown as typeof window.Image;
+        w[PATCH_FLAG] = OriginalImage;
+        window.Image = SlowImage;
+      }
+    } else {
+      return;
+    }
+  }
+};
+
+const uninstallSlowImage = () => {
+  if (typeof window === "undefined") {
+    return;
+  } else {
+    const w = window as PatchedWindow;
+    const original = w[PATCH_FLAG];
+    if (original !== undefined) {
+      window.Image = original;
+      delete w[PATCH_FLAG];
+    }
+  }
+};

package/src/Button/Button.tsx

@@ -0,0 +1,285 @@
+import { Button as BaseButton } from "@base-ui/react/button";
+import type { ComponentProps, ReactNode, Ref } from "react";
+import { useLayoutEffect, useState } from "react";
+import { css, cva, cx } from "../../styled-system/css";
+import type { ControlVariant } from "../../styled-system/recipes";
+import { control } from "../../styled-system/recipes";
+import type { ColorToken } from "../../styled-system/tokens";
+import { useStableRef } from "../_control/useStableRef";
+import type { ExtendProps } from "../extend-props";
+
+export { SIZES, type Size } from "../control-sizes";
+
+export const VARIANTS = [
+  "primary",
+  "solid",
+  "ghost",
+  "outline",
+  "success",
+  "danger",
+  "warning",
+  "accent",
+] as const;
+export type Variant = (typeof VARIANTS)[number];
+
+type CommonProps = Partial<ControlVariant> & {
+  disabled?: boolean | undefined;
+  loading?: boolean | undefined;
+  rounded?: boolean | undefined;
+  variant?: Variant | undefined;
+} & (
+    | {
+        afterIcon?: ReactNode | undefined;
+        beforeIcon?: ReactNode | undefined;
+        children: string;
+        label?: undefined;
+      }
+    | {
+        afterIcon?: undefined;
+        beforeIcon?: undefined;
+        children: ReactNode;
+        label: string;
+      }
+  );
+type Props =
+  | ExtendProps<
+      typeof BaseButton,
+      CommonProps & {
+        href?: undefined;
+      }
+    >
+  | ExtendProps<
+      "a",
+      CommonProps & {
+        href: NonNullable<ComponentProps<"a">["href"]>;
+      }
+    >;
+
+export const Button = ({
+  disabled = false,
+  loading = false,
+  rounded = false,
+  size = "md",
+  variant = "primary",
+  beforeIcon,
+  afterIcon,
+  children,
+  label,
+  ...passthroughProps
+}: Props) => {
+  // The caller's ref as well as this button's own. `sharedProps` below sets
+  // `ref` after `passthroughProps` is spread, so a button that did not pass it
+  // on here would replace the caller's ref with its own and hand the element
+  // back to nobody — see `useStableRef` for what that breaks.
+  //
+  // THE CAST IS THE POLYMORPHISM. `Props` is a union, so the ref arrives as a
+  // ref for an anchor or a ref for a button, and a ref's element is a
+  // parameter — contravariant — so the two do not unify into a ref for either.
+  // What TypeScript cannot see is that the `href` which picked the member of
+  // the union is the same `href` that picks the element below: this is the
+  // anchor's ref exactly when an anchor is what gets drawn.
+  const forwarded = passthroughProps.ref as
+    | Ref<HTMLAnchorElement | HTMLButtonElement>
+    | undefined;
+  const [elementRef, setElementRef] = useStableRef<
+    HTMLAnchorElement | HTMLButtonElement
+  >(forwarded);
+  const [renderedLoading, setRenderedLoading] = useState(loading);
+
+  // Smooth handoff from the `_loading` pulse animation back to the resting
+  // opacity. The pulse is keyframe-based, so removing the `data-loading`
+  // attribute would snap opacity to the rest value instantly. Instead we
+  // (1) snapshot the live computed opacity into an inline `style`, freezing
+  // the in-flight pulse where it was; (2) drop the loading attribute on the
+  // next render; (3) clear the inline style next frame so the control
+  // recipe's `opacity` transition takes over from that frozen starting value
+  // and animates smoothly back to 1.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `elementRef` is a stable RefObject from useStableRef; biome doesn't see through the helper
+  useLayoutEffect(() => {
+    if (loading === true && renderedLoading === false) {
+      setRenderedLoading(true);
+    } else if (renderedLoading === true && loading === false) {
+      if (elementRef.current !== null) {
+        elementRef.current.style.opacity = getComputedStyle(
+          elementRef.current,
+        ).opacity;
+      }
+      // setRenderedLoading triggers a re-render that removes the `data-loading`
+      // attribute; the inline opacity we just set persists into that render and
+      // is cleared on the next frame so the control recipe's `opacity`
+      // transition takes over from the frozen starting value.
+      setRenderedLoading(false);
+      requestAnimationFrame(() => {
+        if (elementRef.current !== null) {
+          elementRef.current.style.opacity = "";
+        }
+      });
+    }
+  }, [loading, renderedLoading]);
+
+  const iconOnly = label !== undefined;
+  const isDisabled = loading === true || disabled === true;
+  const sharedProps = {
+    "aria-busy": loading === true ? true : undefined,
+    "aria-label": label,
+    children: iconOnly ? (
+      <span className={iconOnlyStyles}>{children}</span>
+    ) : (
+      <>
+        {beforeIcon}
+        <span className={labelStyles}>{children}</span>
+        {afterIcon}
+      </>
+    ),
+    className: cx(
+      "group",
+      control({ size }),
+      styles({ iconOnly, rounded, variant }),
+    ),
+    "data-loading": renderedLoading === true ? "" : undefined,
+    ref: setElementRef,
+  };
+
+  if (passthroughProps.href === undefined) {
+    // `<button disabled>` is the native disabled mechanism — fires no click.
+    return (
+      <BaseButton
+        {...passthroughProps}
+        {...sharedProps}
+        disabled={isDisabled}
+      />
+    );
+  } else {
+    // Anchors have no native `disabled` — that attribute would render as
+    // invalid HTML and the link would still navigate. Emulate it with
+    // `aria-disabled`, `data-disabled` (so the control recipe's `_disabled`
+    // condition matches: `:is(:disabled, [data-disabled])`), and an
+    // onClick guard.
+    return (
+      // biome-ignore lint/a11y/noStaticElementInteractions lint/a11y/useKeyWithClickEvents: anchor with href is interactive; onClick is the disabled-state guard that responds to keyboard via the native anchor behavior
+      <a
+        {...passthroughProps}
+        {...sharedProps}
+        aria-disabled={isDisabled === true ? true : undefined}
+        data-disabled={isDisabled === true ? "" : undefined}
+        // biome-ignore lint/a11y/useValidAnchor: anchor is for navigation (has href); onClick only intercepts to block when disabled
+        onClick={(event) => {
+          if (isDisabled === true) {
+            event.preventDefault();
+          } else if (passthroughProps.onClick !== undefined) {
+            passthroughProps.onClick(event);
+          }
+        }}
+        tabIndex={isDisabled === true ? -1 : passthroughProps.tabIndex}
+      />
+    );
+  }
+};
+
+const iconOnlyStyles = css({
+  // Match both `:disabled` (button) and `[data-disabled]` (anchor) so the
+  // icon-only hover/active scale doesn't fire on a "disabled" anchor
+  // (anchors don't get the `:disabled` pseudo-class).
+  ".group:not([data-disabled]):not(:disabled):active &": { scale: 1.1 },
+  ".group:not([data-disabled]):not(:disabled):hover &": { scale: 1.2 },
+  // `inline-flex` + center alignment so the icon sits at the geometric
+  // center of the wrapper rather than on the line-height baseline. A
+  // bare inline wrapper sizes its line box to the font's line-height,
+  // and the inline icon child (img or mask span) settles on the
+  // baseline of that line — pushing the icon visibly down relative to
+  // the button's flex-centered wrapper.
+  alignItems: "center",
+  display: "inline-flex",
+  justifyContent: "center",
+  scale: 1,
+  transition: "scale {durations.faster} {easings.out}",
+});
+
+const labelStyles = css({ paddingInline: "0.25em" });
+
+const tinted = (color: ColorToken) => ({
+  backgroundColor: {
+    _activeEnabled: `color-mix(in oklab, {colors.${color}} 80%, {colors.background})`,
+    _hoverEnabled: `color-mix(in oklab, {colors.${color}} 70%, {colors.foreground})`,
+    base: color,
+  },
+  borderColor: "transparent",
+  color: "background",
+});
+
+const ghost = {
+  backgroundColor: {
+    _activeEnabled: "color-mix(in oklab, {colors.foreground} 10%, transparent)",
+    _hoverEnabled: "color-mix(in oklab, {colors.foreground} 5%, transparent)",
+    base: "transparent",
+  },
+  borderColor: "transparent",
+  color: {
+    _activeEnabled: "color-mix(in oklab, {colors.foreground} 85%, white)",
+    _hoverEnabled: "foreground",
+    base: "muted",
+  },
+};
+
+const styles = cva({
+  base: {
+    animation: {
+      _loading:
+        "pulse {durations.pulse} {easings.in-out} infinite {durations.slow}",
+    },
+    border: "1px solid transparent",
+    cursor: { _disabled: "not-allowed", _loading: "wait", base: "pointer" },
+    filter: { _disabled: "saturate(0.6)", base: "none" },
+    gap: 0,
+    opacity: { _disabled: "disabled", _loading: "pulseMin", base: 1 },
+  },
+  variants: {
+    iconOnly: {
+      true: {
+        aspectRatio: "square",
+        inlineSize: "auto",
+        paddingInline: 0,
+      },
+    },
+    rounded: {
+      true: { borderRadius: "full" },
+    },
+    variant: {
+      accent: tinted("accent"),
+      danger: tinted("danger"),
+      ghost,
+      outline: {
+        ...ghost,
+        borderColor: {
+          _activeEnabled: "foreground",
+          _hoverEnabled: "muted",
+          base: "border",
+        },
+      },
+      primary: {
+        backgroundColor: {
+          _activeEnabled:
+            "color-mix(in oklab, {colors.background} 85%, {colors.foreground})",
+          _hoverEnabled:
+            "color-mix(in oklab, {colors.background} 70%, {colors.foreground})",
+          base: "color-mix(in oklab, {colors.background} 80%, {colors.foreground})",
+        },
+        borderColor: "transparent",
+        color: "foreground",
+      },
+      solid: {
+        backgroundColor: {
+          _activeEnabled:
+            "color-mix(in oklab, {colors.foreground} 60%, {colors.background})",
+          _hoverEnabled:
+            "color-mix(in oklab, {colors.foreground} 80%, {colors.background})",
+          base: "foreground",
+        },
+        borderColor: "transparent",
+        color: "background",
+      },
+      success: tinted("success"),
+      warning: tinted("warning"),
+    },
+  },
+});

package/src/Card/Card.tsx

@@ -0,0 +1,55 @@
+import { useId } from "react";
+
+import { css } from "../../styled-system/css";
+import { stack } from "../../styled-system/patterns";
+import type { ExtendProps } from "../extend-props";
+
+type Props = ExtendProps<"section", { title?: string | undefined }>;
+
+/**
+ * A surface: a padded, bordered container that stacks its children vertically,
+ * with an optional `title` rendered as its heading. The base building block for
+ * the app's chrome panels — settings, sidebars, and the like frame their content
+ * in one rather than each re-deriving the same card treatment. Styling is fixed
+ * (it's a design primitive, not a `className` sink); compose layout inside it.
+ *
+ * A card is a thematic grouping, not a styling wrapper, so it renders a
+ * `<section>`. When it has a `title`, the heading names the section
+ * (`aria-labelledby`), promoting it to a landmark `region` a screen reader can
+ * jump to; an untitled card stays a plain, unnamed section.
+ */
+export const Card = ({ children, title, ...props }: Props) => {
+  const headingId = useId();
+  return (
+    <section
+      aria-labelledby={title === undefined ? undefined : headingId}
+      {...props}
+      className={cardStyles}
+    >
+      {title !== undefined && (
+        <h2 className={headingStyles} id={headingId}>
+          {title}
+        </h2>
+      )}
+      {children}
+    </section>
+  );
+};
+
+// A vertical `stack` carries the flex column + gap; the surface tokens ride
+// alongside. `stack` defaults to `direction: column` and leaves `alignItems`
+// unset, so children stretch to the card's width.
+const cardStyles = stack({
+  backgroundColor: "card",
+  border: "1px solid {colors.border}",
+  borderRadius: "lg",
+  gap: 3,
+  padding: 4,
+});
+
+const headingStyles = css({
+  color: "foreground",
+  fontSize: "sm",
+  fontWeight: "semibold",
+  margin: 0,
+});

package/src/Field/Field.tsx

@@ -0,0 +1,136 @@
+import { Field as BaseField } from "@base-ui/react/field";
+import type { ReactNode } from "react";
+import { useCallback, useState } from "react";
+import { css } from "../../styled-system/css";
+import { flex, grid } from "../../styled-system/patterns";
+import type { ExtendProps } from "../extend-props";
+
+import { FieldErrorPopover } from "./FieldErrorPopover";
+
+type Props = ExtendProps<
+  typeof BaseField.Root,
+  {
+    children: ReactNode;
+    error?: ReactNode | undefined;
+    hint?: ReactNode | undefined;
+    label?: ReactNode | undefined;
+  }
+>;
+
+export const Field = ({
+  children,
+  error,
+  hint,
+  invalid,
+  label,
+  ...props
+}: Props) => {
+  const [controlElement, setControlElement] = useState<
+    HTMLDivElement | undefined
+  >(undefined);
+  // React passes `null` to ref callbacks on unmount; map that to `undefined`
+  // to keep the codebase's no-`null` convention.
+  const setControlElementRef = useCallback((el: HTMLDivElement | null) => {
+    setControlElement(el ?? undefined);
+  }, []);
+
+  return (
+    <BaseField.Root
+      {...props}
+      className={rootStyles}
+      // Stable hook for wrapperBase's "label-hover → control hover" rule
+      // (`[data-domicile-field]:has(> label:hover) > div > &`). base-ui doesn't
+      // emit a discriminating attribute on the Field root, and a generic
+      // `label:hover ~ div *` selector would leak hover state into unrelated
+      // controls that happen to follow a hovered label on the page.
+      data-domicile-field=""
+      invalid={error === undefined ? invalid : true}
+    >
+      {label !== undefined && (
+        <BaseField.Label className={labelStyles}>{label}</BaseField.Label>
+      )}
+      <div className={controlRowStyles} ref={setControlElementRef}>
+        {children}
+      </div>
+      {hint !== undefined && (
+        <BaseField.Description className={hintStyles}>
+          {hint}
+        </BaseField.Description>
+      )}
+      <BaseField.Validity>
+        {({ error: nativeError, validity }) => (
+          <FieldErrorPopover
+            anchor={controlElement}
+            error={resolveError(
+              error,
+              validity.valid ?? undefined,
+              nativeError,
+            )}
+          />
+        )}
+      </BaseField.Validity>
+    </BaseField.Root>
+  );
+};
+
+const resolveError = (
+  explicit: ReactNode,
+  valid: boolean | undefined,
+  nativeMessage: string,
+): ReactNode =>
+  explicit ??
+  (valid === false && nativeMessage !== "" ? nativeMessage : undefined);
+
+// No flex `gap` on the root — the label↔control and control↔hint gaps
+// are set independently via directional margins on the label and hint
+// (`marginBlockEnd` / `marginBlockStart` below) so the hint can sit
+// tighter under the control than the label does above it.
+const rootStyles = flex({
+  cursor: { _disabled: "not-allowed", base: "auto" },
+  direction: "column",
+});
+
+const controlRowStyles = grid({
+  alignItems: "stretch",
+  gap: 1.5,
+  gridAutoColumns: "auto",
+  gridAutoFlow: "column",
+  gridTemplateColumns: "minmax(0, 1fr)",
+});
+
+const labelStyles = css({
+  _disabled: { color: "muted", opacity: "disabled" },
+  _invalid: { color: "danger" },
+  color: "foreground",
+  // Pointer cursor on the label signals "clicking me focuses the
+  // control" — the conventional affordance for a form label, and
+  // matches the wrapped control's own cursor: when the control is
+  // disabled the label switches to not-allowed alongside it.
+  cursor: { _disabled: "not-allowed", base: "pointer" },
+  // `display: block` makes the label fill the field's full inline width
+  // so clicks anywhere on the row — not just on the text glyphs — hit
+  // the label and forward to the control. The space between the label
+  // and the control is `paddingBlockEnd` (rather than `marginBlockEnd`
+  // or the parent's flex `gap`) for the same reason: it counts as part
+  // of the label's hit region instead of being inert space below it.
+  display: "block",
+  fontSize: "xs",
+  fontVariantNumeric: "tabular-nums",
+  fontWeight: "medium",
+  letterSpacing: "normal",
+  lineHeight: "snug",
+  margin: 0,
+  paddingBlockEnd: 2,
+});
+
+const hintStyles = css({
+  _disabled: { opacity: "disabled" },
+  color: "muted",
+  fontSize: "xs",
+  fontVariantNumeric: "tabular-nums",
+  fontWeight: "normal",
+  letterSpacing: "normal",
+  lineHeight: "normal",
+  margin: 0,
+  marginBlockStart: 0.5,
+});