@dxos/react-ui 0.8.4-main.ead640a → 0.8.4-main.effb148878

package/src/components/Icon/Icon.stories.tsx

@@ -0,0 +1,143 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { IconBase, type IconProps, type IconWeight } from '@phosphor-icons/react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { type FC, type ReactElement, type SVGProps, forwardRef } from 'react';
+
+import { getSize, iconSize, mx } from '@dxos/ui-theme';
+
+import { withTheme } from '../../testing';
+import { Icon } from './Icon';
+
+/**
+ * Create icon from serializable data.
+ * https://github.com/phosphor-icons/react#custom-icons
+ * https://github.com/phosphor-icons/core/tree/main/assets
+ */
+const createIcon = ({
+  name,
+  weights,
+}: {
+  name: string;
+  weights: Record<string, SVGProps<SVGPathElement>[]>;
+}): FC<IconProps> => {
+  const CustomIcon = forwardRef<SVGSVGElement, IconProps>((props, ref) => (
+    <IconBase
+      ref={ref}
+      {...props}
+      weights={
+        new Map<IconWeight, ReactElement>(
+          Object.entries(weights).map(
+            ([key, paths]) =>
+              [
+                key,
+                <>
+                  {paths.map((props, i) => (
+                    <path key={`${key}-${i}`} {...props} />
+                  ))}
+                </>,
+              ] as [IconWeight, ReactElement],
+          ),
+        )
+      }
+    />
+  ));
+
+  CustomIcon.displayName = name;
+  return CustomIcon;
+};
+
+const meta = {
+  title: 'ui/react-ui-core/components/Icon',
+  component: Icon,
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof Icon>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    icon: 'ph--github-logo--regular',
+  },
+};
+
+export const Static: Story = {
+  args: {
+    icon: 'ph--github-logo--regular',
+    classNames: getSize(8),
+  },
+};
+
+export const Dynamic: Story = {
+  args: {
+    icon: 'ph--github-logo--regular',
+  },
+  render: (args) => {
+    return (
+      <div className='flex gap-4'>
+        <Icon {...args} />
+        <div className='flex gap-4' style={iconSize(8)}>
+          <Icon {...args} />
+          <div className='flex gap-4' style={iconSize(null)}>
+            <Icon {...args} />
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Custom = {
+  render: ({ CustomIcon }: { CustomIcon: FC<IconProps> }) => {
+    return (
+      <div className='grid grid-cols-2 gap-8'>
+        <CustomIcon weight={'regular'} className={mx(getSize(16))} />
+        <Icon icon='ph--github-logo--regular' classNames={mx(getSize(16))} />
+      </div>
+    );
+  },
+  args: {
+    CustomIcon: createIcon({
+      name: 'GithubLogo',
+      weights: {
+        // https://github.com/phosphor-icons/core/tree/main/assets
+        // <path d="M119.83,56A52,52,0,0,0,76,32a51.92,51.92,0,0,0-3.49,44.7A49.28,49.28,0,0,0,64,104v8a48,48,0,0,0,48,48h48a48,48,0,0,0,48-48v-8a49.28,49.28,0,0,0-8.51-27.3A51.92,51.92,0,0,0,196,32a52,52,0,0,0-43.83,24Z" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/>
+        // <path d="M104,232V192a32,32,0,0,1,32-32h0a32,32,0,0,1,32,32v40" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/>
+        // <path d="M104,208H72a32,32,0,0,1-32-32A32,32,0,0,0,8,144" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="16"/>
+        regular: [
+          {
+            d: 'M119.83,56A52,52,0,0,0,76,32a51.92,51.92,0,0,0-3.49,44.7A49.28,49.28,0,0,0,64,104v8a48,48,0,0,0,48,48h48a48,48,0,0,0,48-48v-8a49.28,49.28,0,0,0-8.51-27.3A51.92,51.92,0,0,0,196,32a52,52,0,0,0-43.83,24Z',
+            fill: 'none',
+            stroke: 'currentColor',
+            strokeLinecap: 'round',
+            strokeLinejoin: 'round',
+            strokeWidth: '16',
+          },
+          {
+            d: 'M104,232V192a32,32,0,0,1,32-32h0a32,32,0,0,1,32,32v40',
+            fill: 'none',
+            stroke: 'currentColor',
+            strokeLinecap: 'round',
+            strokeLinejoin: 'round',
+            strokeWidth: '16',
+          },
+          {
+            d: 'M104,208H72a32,32,0,0,1-32-32A32,32,0,0,0,8,144',
+            fill: 'none',
+            stroke: 'currentColor',
+            strokeLinecap: 'round',
+            strokeLinejoin: 'round',
+            strokeWidth: '16',
+          },
+        ],
+      },
+    }),
+  },
+};

package/src/components/Icon/Icon.theme.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { getSize, mx } from '@dxos/ui-theme';
+import { type ComponentFunction, type Size, type Theme } from '@dxos/ui-types';
+
+export type IconStyleProps = {
+  size?: Size;
+};
+
+/**
+ * Size can be specified directly, or inherited from a container (e.g., toolbar).
+ */
+const root: ComponentFunction<IconStyleProps> = ({ size }, etc) => {
+  return mx(
+    'shrink-0 text-[var(--icons-color,currentColor)]',
+    size
+      ? getSize(size)
+      : '[width:var(--icon-size,var(--dx-default-icons-size))] [height:var(--icon-size,var(--dx-default-icons-size))]',
+    etc,
+  );
+};
+
+export const iconTheme: Theme<IconStyleProps> = {
+  root,
+};

package/src/components/Icon/Icon.tsx

@@ -3,9 +3,9 @@
 //
 
 import { type Primitive } from '@radix-ui/react-primitive';
-import React, { type ComponentPropsWithRef, forwardRef, memo } from 'react';
+import React, { type ComponentPropsWithRef, forwardRef, memo, useMemo } from 'react';
 
-import { type Size } from '@dxos/react-ui-types';
+import { type Size } from '@dxos/ui-types';
 
 import { useIconHref, useThemeContext } from '../../hooks';
 import { type ThemedClassName } from '../../util';
@@ -13,14 +13,25 @@ import { type ThemedClassName } from '../../util';
 export type IconProps = ThemedClassName<ComponentPropsWithRef<typeof Primitive.svg>> & {
   icon: string;
   size?: Size;
+  synchronized?: boolean;
 };
 
+/**
+ * The Icon's size can be set directly or inherited from the `--dx-icon-size` CSS variable.
+ */
 export const Icon = memo(
-  forwardRef<SVGSVGElement, IconProps>(({ icon, classNames, size = 4, ...props }, forwardedRef) => {
+  forwardRef<SVGSVGElement, IconProps>(({ classNames, icon, size, synchronized, style, ...props }, forwardedRef) => {
     const { tx } = useThemeContext();
+    const spinDelay = useMemo(() => (synchronized ? `${-(Date.now() % 1_000)}ms` : undefined), [synchronized]);
     const href = useIconHref(icon);
+
     return (
-      <svg {...props} className={tx('icon.root', 'icon', { size }, classNames)} ref={forwardedRef}>
+      <svg
+        {...props}
+        style={{ ...style, animationDelay: spinDelay }}
+        className={tx('icon.root', { size }, classNames)}
+        ref={forwardedRef}
+      >
         <use href={href} />
       </svg>
     );

package/src/components/Image/Image.stories.tsx

@@ -0,0 +1,86 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+
+import { random } from '@dxos/random';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { Image } from './Image';
+
+const seed = Math.random();
+
+random.seed(seed);
+
+const meta = {
+  title: 'ui/react-ui-core/components/Image',
+  component: Image,
+  render: (args) => (
+    <div className='absolute inset-0 flex justify-center items-center'>
+      <Image {...args} />
+    </div>
+  ),
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof Image>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    src: random.image.url(),
+  },
+};
+
+const classNames = 'h-[12rem] w-[18rem]';
+
+/**
+ * Access to image at 'https://dxos.network/dxos-logotype-blue.png'
+ * from origin 'http://localhost:9009' has been blocked by CORS policy:
+ * No 'Access-Control-Allow-Origin' header is present on the requested resource.
+ */
+export const Cors: Story = {
+  args: {
+    src: 'https://dxos.network/dxos-logotype-blue.png',
+    classNames,
+  },
+};
+
+export const Corners: Story = {
+  args: {
+    src: 'https://picsum.photos/seed/picsum/200/200',
+    classNames,
+  },
+};
+
+export const SVG: Story = {
+  args: {
+    src: 'https://dxos.network/bg-kube.svg',
+    classNames,
+  },
+};
+
+export const Many: Story = {
+  args: {
+    src: 'https://dxos.network/bg-kube.svg',
+  },
+  render: () => {
+    const images = useMemo(
+      () => Array.from({ length: 9 }, (_, i) => `https://picsum.photos/seed/${seed + i}/500/500`),
+      [],
+    );
+    return (
+      <div className='w-[60rem] grid grid-cols-3 grid-rows-3 gap-8'>
+        {images.map((src, i) => (
+          <Image key={i} src={src} classNames={classNames} />
+        ))}
+      </div>
+    );
+  },
+};

package/src/components/Image/Image.tsx

@@ -0,0 +1,246 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { type SyntheticEvent, useCallback, useRef, useState } from 'react';
+
+import { type ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+const cache = new Map<string, string>();
+
+export type ImageProps = ThemedClassName<
+  {
+    src: string;
+    alt?: string;
+    fit?: 'contain' | 'cover';
+    crossOrigin?: 'anonymous' | 'use-credentials' | '';
+  } & ColorOptions
+>;
+
+export const Image = ({
+  classNames,
+  src,
+  alt = '',
+  fit = 'contain',
+  crossOrigin = 'anonymous',
+  sampleSize = 64,
+  contrast = 0.9,
+}: ImageProps) => {
+  const [crossOriginState, setCrossOriginState] = useState<ImageProps['crossOrigin']>(crossOrigin);
+  const [dominantColor, setDominantColor] = useState<string | undefined>(undefined);
+  const [imageLoaded, setImageLoaded] = useState<boolean>(false);
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  // CORS not supported by server.
+  const handleImageError = (): void => {
+    setCrossOriginState(undefined);
+  };
+
+  const handleImageLoad = useCallback(
+    ({ target }: SyntheticEvent<HTMLImageElement>): void => {
+      const rgb = cache.get(src);
+      if (rgb) {
+        setDominantColor(rgb);
+        setImageLoaded(true);
+        return;
+      }
+
+      const img = target as HTMLImageElement;
+      if (!canvasRef.current) {
+        return;
+      }
+
+      try {
+        const color = extractDominantColor(canvasRef.current, img, { sampleSize, contrast });
+        if (color) {
+          const rgb = `rgb(${color[0]}, ${color[1]}, ${color[2]})`;
+          cache.set(src, rgb);
+          setDominantColor(rgb);
+        }
+      } catch {
+        setCrossOriginState(undefined);
+      }
+
+      setImageLoaded(true);
+    },
+    [sampleSize, contrast, src],
+  );
+
+  return (
+    <div
+      // `isolate` (`isolation: isolate`) creates a new stacking context so
+      // the inner <img>'s `z-10` stays scoped to this wrapper. Without it
+      // the z-10 leaks into the parent's stacking context and elevates the
+      // image above any pseudo-element rings (e.g. Focus.Item's
+      // `dx-ring-pseudo` `::after`) painted on ancestors — most visibly,
+      // the focus ring on a Card containing a Card.Poster.
+      className={mx(
+        `relative flex w-full justify-center overflow-hidden transition-all duration-700 isolate`,
+        classNames,
+      )}
+      style={{
+        backgroundColor: dominantColor,
+      }}
+    >
+      {/* Hidden canvas for color extraction. */}
+      <canvas ref={canvasRef} style={{ display: 'none' }} aria-hidden='true' />
+
+      {/* Background gradient overlay for smooth transition. */}
+      <div
+        className='absolute inset-0 pointer-events-none'
+        style={{
+          background: dominantColor
+            ? `radial-gradient(circle at center, transparent 30%, ${dominantColor} 100%)`
+            : undefined,
+          transition: 'opacity 0.7s ease-in-out',
+          opacity: 0.5,
+        }}
+      />
+
+      <img
+        src={src}
+        alt={alt}
+        crossOrigin={crossOriginState}
+        onError={handleImageError}
+        onLoad={handleImageLoad}
+        className={mx(
+          'z-10 transition-opacity duration-500',
+          fit === 'cover' ? 'w-full h-full object-cover' : 'object-contain',
+        )}
+        style={{
+          opacity: imageLoaded ? 1 : 0,
+        }}
+      />
+    </div>
+  );
+};
+
+type ColorOptions = {
+  sampleSize?: number;
+  contrast?: number;
+};
+
+/**
+ * Get dominant color from image (esp. from corners).
+ */
+const extractDominantColor = (
+  canvas: HTMLCanvasElement,
+  img: HTMLImageElement,
+  { sampleSize = 64, contrast = 0.95 }: ColorOptions,
+): [number, number, number] | null => {
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    return null;
+  }
+
+  // Draw the image scaled down.
+  canvas.width = sampleSize;
+  canvas.height = sampleSize;
+  ctx.drawImage(img, 0, 0, sampleSize, sampleSize);
+
+  // Get image data.
+  const imageData = ctx.getImageData(0, 0, sampleSize, sampleSize);
+  const pixels = imageData.data;
+
+  // Check for transparent background.
+  if (isTransparent(pixels, sampleSize)) {
+    return null;
+  }
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let totalWeight = 0;
+
+  // Define corner sampling areas (e.g., 25% of each dimension from each corner).
+  const cornerSize = Math.floor(sampleSize * 0.125);
+
+  // Sample only pixels in corner areas.
+  for (let y = 0; y < sampleSize; y++) {
+    for (let x = 0; x < sampleSize; x++) {
+      // Check if pixel is in any corner area.
+      const isInTopLeft = x < cornerSize && y < cornerSize;
+      const isInTopRight = x >= sampleSize - cornerSize && y < cornerSize;
+      const isInBottomLeft = x < cornerSize && y >= sampleSize - cornerSize;
+      const isInBottomRight = x >= sampleSize - cornerSize && y >= sampleSize - cornerSize;
+      if (!isInTopLeft && !isInTopRight && !isInBottomLeft && !isInBottomRight) {
+        continue; // Skip pixels not in corner areas.
+      }
+
+      const i = (y * sampleSize + x) * 4;
+      const red = pixels[i];
+      const green = pixels[i + 1];
+      const blue = pixels[i + 2];
+      const alpha = pixels[i + 3];
+
+      // Skip transparent pixels.
+      if (alpha === 0) {
+        continue;
+      }
+
+      // Calculate saturation to weight vibrant colors more.
+      const max = Math.max(red, green, blue);
+      const min = Math.min(red, green, blue);
+      const saturation = max === 0 ? 0 : (max - min) / max;
+      const weight = 1 + saturation * 2;
+
+      r += red * weight;
+      g += green * weight;
+      b += blue * weight;
+      totalWeight += weight;
+    }
+  }
+
+  if (totalWeight > 0) {
+    // Slightly darken the color for better contrast.
+    r = Math.round(Math.round(r / totalWeight) * contrast);
+    g = Math.round(Math.round(g / totalWeight) * contrast);
+    b = Math.round(Math.round(b / totalWeight) * contrast);
+    return [r, g, b];
+  }
+
+  return null;
+};
+
+/**
+ * Detects if an image has a transparent background by examining edge pixels.
+ * @param pixels - Image pixel data from canvas
+ * @param sampleSize - Size of the sampled image
+ * @param threshold - Percentage threshold for considering background transparent (default: 0.5)
+ * @returns True if the image has a transparent background
+ */
+const isTransparent = (pixels: Uint8ClampedArray, sampleSize: number, threshold: number = 0.5): boolean => {
+  let edgeTransparentPixels = 0;
+  const edgePixels = sampleSize * 4 - 4; // Perimeter minus corners counted twice.
+
+  for (let x = 0; x < sampleSize; x++) {
+    // Top edge.
+    const topIndex = x * 4;
+    if (pixels[topIndex + 3] === 0) {
+      edgeTransparentPixels++;
+    }
+
+    // Bottom edge.
+    const bottomIndex = ((sampleSize - 1) * sampleSize + x) * 4;
+    if (pixels[bottomIndex + 3] === 0) {
+      edgeTransparentPixels++;
+    }
+  }
+
+  for (let y = 1; y < sampleSize - 1; y++) {
+    // Left edge.
+    const leftIndex = y * sampleSize * 4;
+    if (pixels[leftIndex + 3] === 0) {
+      edgeTransparentPixels++;
+    }
+
+    // Right edge.
+    const rightIndex = (y * sampleSize + sampleSize - 1) * 4;
+    if (pixels[rightIndex + 3] === 0) {
+      edgeTransparentPixels++;
+    }
+  }
+
+  return edgeTransparentPixels / edgePixels > threshold;
+};

package/src/components/Image/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './Image';