@dxos/ui-theme 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/src/typings.d.ts

@@ -5,4 +5,3 @@
 declare module 'fast-glob';
 declare module 'tailwindcss/stubs/config.full.js';
 declare module 'tailwindcss-radix';
-declare module 'tailwindcss-logical';

package/src/{styles/fragments → util}/elevation.ts

@@ -4,14 +4,12 @@
 
 import { type ComponentFragment, type Elevation, type SurfaceLevel } from '@dxos/ui-types';
 
-/**
- * @deprecated
- */
-export const contentShadow: ComponentFragment<{ elevation?: Elevation }> = (_) => ['shadow-none'];
-
-// TODO(thure): These should become tokens.
 export const surfaceShadow: ComponentFragment<{ elevation?: Elevation }> = ({ elevation }) => [
-  elevation === 'positioned' ? 'shadow' : elevation === 'dialog' || elevation === 'toast' ? 'shadow-md' : 'shadow-none',
+  elevation === 'positioned'
+    ? 'shadow-sm'
+    : elevation === 'dialog' || elevation === 'toast'
+      ? 'shadow-md'
+      : 'shadow-none',
 ];
 
 export const surfaceZIndex: ComponentFragment<{ level?: SurfaceLevel; elevation?: Elevation }> = ({
@@ -20,7 +18,7 @@ export const surfaceZIndex: ComponentFragment<{ level?: SurfaceLevel; elevation?
 }) => {
   switch (level) {
     case 'tooltip':
-      return elevation === 'dialog' ? ['z-[53]'] : elevation === 'toast' ? ['z-[43]'] : ['z-30'];
+      return elevation === 'dialog' ? ['z-[53]'] : elevation === 'toast' ? ['z-[43]'] : ['z-50'];
     case 'menu':
       return elevation === 'dialog' ? ['z-[52]'] : elevation === 'toast' ? ['z-[42]'] : ['z-20'];
     default:

package/src/util/hash-styles.ts

@@ -6,163 +6,183 @@ import { type ChromaticPalette } from '@dxos/ui-types';
 
 export type Hue = ChromaticPalette | 'neutral';
 
-// TODO(burdon): Rename?
+// TODO(burdon): Reconcile with ui-theme/theme/roles.css
 export type ColorStyles = {
   hue: Hue;
-  text: string;
-  icon: string;
-  bg: string;
-  surface: string;
-  border: string;
+  fill: string; // -fill
+  surface: string; // -surface
+  surfaceText: string; // -surface-text
+  text: string; // -text
+  border: string; // -border
 };
 
-const neutralColor: ColorStyles = {
+const neutral: ColorStyles = {
   hue: 'neutral',
-  text: 'text-neutralFill',
-  icon: 'text-neutralSurfaceText',
-  bg: 'bg-neutralFill',
-  surface: 'bg-neutralSurface',
-  border: 'border-neutralFill',
+  fill: 'bg-neutral-fill',
+  surface: 'bg-neutral-surface',
+  surfaceText: 'text-neutral-surface-text',
+  text: 'text-neutral-text',
+  border: 'border-neutral-border',
 };
 
-// NOTE: Don't include blue/red which are used as system colors.
-// NOTE: Cordinated with `tag.css`.
+// NOTE: Coordinated with `tag.css`.
 // https://github.com/dxos/dxos/blob/main/packages/ui/react-ui-theme/src/styles/layers/tag.css
-export const styles: ColorStyles[] = [
+const styles: ColorStyles[] = [
+  {
+    hue: 'red',
+    fill: 'bg-red-fill',
+    surface: 'bg-red-surface',
+    surfaceText: 'text-red-surface-text',
+    text: 'text-red-text',
+    border: 'border-red-border',
+  },
   {
     hue: 'orange',
-    text: 'text-orangeFill',
-    icon: 'text-orangeSurfaceText',
-    bg: 'bg-orangeFill',
-    surface: 'bg-orangeSurface',
-    border: 'border-orangeFill',
+    fill: 'bg-orange-fill',
+    surface: 'bg-orange-surface',
+    surfaceText: 'text-orange-surface-text',
+    text: 'text-orange-text',
+    border: 'border-orange-border',
   },
   {
     hue: 'amber',
-    text: 'text-amberFill',
-    icon: 'text-amberSurfaceText',
-    bg: 'bg-amberFill',
-    surface: 'bg-amberSurface',
-    border: 'border-amberFill',
+    fill: 'bg-amber-fill',
+    surface: 'bg-amber-surface',
+    surfaceText: 'text-amber-surface-text',
+    text: 'text-amber-text',
+    border: 'border-amber-border',
   },
   {
     hue: 'yellow',
-    text: 'text-yellowFill',
-    icon: 'text-yellowSurfaceText',
-    bg: 'bg-yellowFill',
-    surface: 'bg-yellowSurface',
-    border: 'border-yellowFill',
+    fill: 'bg-yellow-fill',
+    surface: 'bg-yellow-surface',
+    surfaceText: 'text-yellow-surface-text',
+    text: 'text-yellow-text',
+    border: 'border-yellow-border',
   },
   {
     hue: 'lime',
-    text: 'text-limeFill',
-    icon: 'text-limeSurfaceText',
-    bg: 'bg-limeFill',
-    surface: 'bg-limeSurface',
-    border: 'border-limeFill',
+    fill: 'bg-lime-fill',
+    surface: 'bg-lime-surface',
+    surfaceText: 'text-lime-surface-text',
+    text: 'text-lime-text',
+    border: 'border-lime-border',
   },
   {
     hue: 'green',
-    text: 'text-greenFill',
-    icon: 'text-greenSurfaceText',
-    bg: 'bg-greenFill',
-    surface: 'bg-greenSurface',
-    border: 'border-greenFill',
+    fill: 'bg-green-fill',
+    surface: 'bg-green-surface',
+    surfaceText: 'text-green-surface-text',
+    text: 'text-green-text',
+    border: 'border-green-border',
   },
   {
     hue: 'emerald',
-    text: 'text-emeraldFill',
-    icon: 'text-emeraldSurfaceText',
-    bg: 'bg-emeraldFill',
-    surface: 'bg-emeraldSurface',
-    border: 'border-emeraldFill',
+    fill: 'bg-emerald-fill',
+    surface: 'bg-emerald-surface',
+    surfaceText: 'text-emerald-surface-text',
+    text: 'text-emerald-text',
+    border: 'border-emerald-border',
   },
   {
     hue: 'teal',
-    text: 'text-tealFill',
-    icon: 'text-tealSurfaceText',
-    bg: 'bg-tealFill',
-    surface: 'bg-tealSurface',
-    border: 'border-tealFill',
+    fill: 'bg-teal-fill',
+    surface: 'bg-teal-surface',
+    surfaceText: 'text-teal-surface-text',
+    text: 'text-teal-text',
+    border: 'border-teal-border',
   },
   {
     hue: 'cyan',
-    text: 'text-cyanFill',
-    icon: 'text-cyanSurfaceText',
-    bg: 'bg-cyanFill',
-    surface: 'bg-cyanSurface',
-    border: 'border-cyanFill',
+    fill: 'bg-cyan-fill',
+    surface: 'bg-cyan-surface',
+    surfaceText: 'text-cyan-surface-text',
+    text: 'text-cyan-text',
+    border: 'border-cyan-border',
   },
   {
     hue: 'sky',
-    text: 'text-skyFill',
-    icon: 'text-skySurfaceText',
-    bg: 'bg-skyFill',
-    surface: 'bg-skySurface',
-    border: 'border-skyFill',
+    fill: 'bg-sky-fill',
+    surface: 'bg-sky-surface',
+    surfaceText: 'text-sky-surface-text',
+    text: 'text-sky-text',
+    border: 'border-sky-border',
+  },
+  {
+    hue: 'blue',
+    fill: 'bg-blue-fill',
+    surface: 'bg-blue-surface',
+    surfaceText: 'text-blue-surface-text',
+    text: 'text-blue-text',
+    border: 'border-blue-border',
   },
   {
     hue: 'indigo',
-    text: 'text-indigoFill',
-    icon: 'text-indigoSurfaceText',
-    bg: 'bg-indigoFill',
-    surface: 'bg-indigoSurface',
-    border: 'border-indigoFill',
+    fill: 'bg-indigo-fill',
+    surface: 'bg-indigo-surface',
+    surfaceText: 'text-indigo-surface-text',
+    text: 'text-indigo-text',
+    border: 'border-indigo-border',
   },
   {
     hue: 'violet',
-    text: 'text-violetFill',
-    icon: 'text-violetSurfaceText',
-    bg: 'bg-violetFill',
-    surface: 'bg-violetSurface',
-    border: 'border-violetFill',
+    fill: 'bg-violet-fill',
+    surface: 'bg-violet-surface',
+    surfaceText: 'text-violet-surface-text',
+    text: 'text-violet-text',
+    border: 'border-violet-border',
   },
   {
     hue: 'purple',
-    text: 'text-purpleFill',
-    icon: 'text-purpleSurfaceText',
-    bg: 'bg-purpleFill',
-    surface: 'bg-purpleSurface',
-    border: 'border-purpleFill',
+    fill: 'bg-purple-fill',
+    surface: 'bg-purple-surface',
+    surfaceText: 'text-purple-surface-text',
+    text: 'text-purple-text',
+    border: 'border-purple-border',
   },
   {
     hue: 'fuchsia',
-    text: 'text-fuchsiaFill',
-    icon: 'text-fuchsiaSurfaceText',
-    bg: 'bg-fuchsiaFill',
-    surface: 'bg-fuchsiaSurface',
-    border: 'border-fuchsiaFill',
+    fill: 'bg-fuchsia-fill',
+    surface: 'bg-fuchsia-surface',
+    surfaceText: 'text-fuchsia-surface-text',
+    text: 'text-fuchsia-text',
+    border: 'border-fuchsia-border',
   },
   {
-    hue: 'rose',
-    text: 'text-roseFill',
-    icon: 'text-roseSurfaceText',
-    bg: 'bg-roseFill',
-    surface: 'bg-roseSurface',
-    border: 'border-roseFill',
+    hue: 'pink',
+    fill: 'bg-pink-fill',
+    surface: 'bg-pink-surface',
+    surfaceText: 'text-pink-surface-text',
+    text: 'text-pink-text',
+    border: 'border-pink-border',
   },
   {
-    hue: 'pink',
-    text: 'text-pinkFill',
-    icon: 'text-pinkSurfaceText',
-    bg: 'bg-pinkFill',
-    surface: 'bg-pinkSurface',
-    border: 'border-pinkFill',
+    hue: 'rose',
+    fill: 'bg-rose-fill',
+    surface: 'bg-rose-surface',
+    surfaceText: 'text-rose-surface-text',
+    text: 'text-rose-text',
+    border: 'border-rose-border',
   },
 ];
 
-export const getStyles = (hue: string): ColorStyles => {
-  return styles.find((color) => color.hue === hue) || neutralColor;
+export const palette = {
+  neutral,
+  hues: styles,
 };
 
-export const getHashHue = (id: string | undefined): Hue => {
-  return id ? styles[getHash(id) % styles.length].hue : 'neutral';
+// TODO(burdon): Rename getClassNames.
+export const getStyles = (hue: string): ColorStyles => {
+  return styles.find((color) => color.hue === hue) || neutral;
 };
 
 // TODO(thure): Reconcile with `to-fallback.ts` which exports `toHue` which overlaps a lot.
 export const getHashStyles = (id: string | undefined): ColorStyles => {
-  const hue = getHashHue(id);
-  return getStyles(hue);
+  return getStyles(getHashHue(id));
+};
+
+export const getHashHue = (id: string | undefined): Hue => {
+  return id ? styles[getHash(id) % styles.length].hue : 'neutral';
 };
 
 const getHash = (id: string): number => id.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0);

package/src/util/index.ts

@@ -2,5 +2,8 @@
 // Copyright 2022 DXOS.org
 //
 
+export * from './elevation';
 export * from './hash-styles';
 export * from './mx';
+export * from './size';
+export * from './valence';

package/src/util/mx.ts

@@ -2,50 +2,166 @@
 // Copyright 2022 DXOS.org
 //
 
+import {
+  Children,
+  createElement,
+  forwardRef,
+  type ForwardRefExoticComponent,
+  type ForwardedRef,
+  type HTMLAttributes,
+  isValidElement,
+  type ReactNode,
+  type RefAttributes,
+} from 'react';
 import { extendTailwindMerge, validators } from 'tailwind-merge';
 
-import { type WithLogicalClassGroups, withLogical } from './withLogical';
-
-type AdditionalClassGroups = 'density' | 'dx-focus-ring' | WithLogicalClassGroups;
-
-export const mx = extendTailwindMerge<AdditionalClassGroups>(
-  {
-    extend: {
-      classGroups: {
-        'font-family': ['font-body', 'font-mono'],
-        'font-weight': [
-          // App weights
-          'font-thin',
-          'font-extralight',
-          'font-light',
-          'font-normal',
-          'font-medium',
-          'font-semibold',
-          'font-bold',
-          'font-extrabold',
-          'font-black',
-          // Arbitrary numbers
-          validators.isArbitraryNumber,
-        ],
-        density: ['density-fine', 'density-coarse'],
-        'dx-focus-ring': [
-          'dx-focus-ring',
-          'dx-focus-ring-inset',
-          'dx-focus-ring-always',
-          'dx-focus-ring-inset-always',
-          'dx-focus-ring-group',
-          'dx-focus-ring-group-x',
-          'dx-focus-ring-group-y',
-          'dx-focus-ring-group-always',
-          'dx-focus-ring-group-x-always',
-          'dx-focus-ring-group-y-always',
-          'dx-focus-ring-inset-over-all',
-          'dx-focus-ring-inset-over-all-always',
-          'dx-focus-ring-main',
-          'dx-focus-ring-main-always',
-        ],
-      },
+import { log } from '@dxos/log';
+import { ThemedClassName, type ComposableProps, type SlottableProps } from '@dxos/ui-types';
+
+type AdditionalClassGroups = 'density' | 'dx-focus-ring';
+
+export const mx = extendTailwindMerge<AdditionalClassGroups>({
+  extend: {
+    classGroups: {
+      'font-family': ['font-body', 'font-mono'],
+      'font-weight': [
+        // App weights
+        'font-thin',
+        'font-extralight',
+        'font-light',
+        'font-normal',
+        'font-medium',
+        'font-semibold',
+        'font-bold',
+        'font-extrabold',
+        'font-black',
+        // Arbitrary numbers
+        validators.isArbitraryNumber,
+      ],
+
+      density: ['dx-density-fine', 'dx-density-coarse'],
+
+      'dx-focus-ring': [
+        'dx-focus-ring',
+        'dx-focus-ring-inset',
+        'dx-focus-ring-always',
+        'dx-focus-ring-inset-always',
+        'dx-focus-ring-group',
+        'dx-focus-ring-group-x',
+        'dx-focus-ring-group-y',
+        'dx-focus-ring-group-always',
+        'dx-focus-ring-group-x-always',
+        'dx-focus-ring-group-y-always',
+        'dx-focus-ring-inset-over-all',
+        'dx-focus-ring-inset-over-all-always',
+        'dx-focus-ring-main',
+        'dx-focus-ring-main-always',
+      ],
     },
   },
-  withLogical,
-);
+});
+
+/**
+ * Reconciles className properties from a parent slot.
+ * - `className` is set by the Slot merge mechanism.
+ * - `classNames` is the consumer-facing prop for theming overrides.
+ * Use `composableProps` to reconcile both into a single `className`.
+ */
+// TODO(burdon): Move to react-ui.
+export const composableProps = <P extends HTMLElement = HTMLElement>(
+  { className, classNames, role, ...props }: ComposableProps,
+  { classNames: defaultClassNames, ...defaults }: ThemedClassName<Partial<HTMLAttributes<P>>> | undefined = {},
+) => ({
+  // Default props.
+  ...(defaults as object),
+
+  // Spread supplied props; prefer explicit role, then defaults role, then 'none'.
+  role: (role ?? (defaults as Record<string, string>).role ?? 'none') as string,
+  ...props,
+
+  // Compose classnames.
+  className: mx(defaultClassNames, className, classNames),
+});
+
+/**
+ * Factory for slottable components.
+ * The implementation receives full `HTMLAttributes<E>` so it can destructure `role`, `style`, etc.
+ * Consumers see only `SlottableProps<P>` — a narrow type exposing `classNames`, `className`,
+ * `children`, `asChild`, and the custom props `P`.
+ *
+ * @example
+ * ```tsx
+ * const MyPanel = slottable<HTMLDivElement, { border?: boolean }>(
+ *   ({ children, asChild, border, ...props }, forwardedRef) => {
+ *     const Comp = asChild ? Slot : Primitive.div;
+ *     return (
+ *       <Comp {...composableProps(props, { classNames: border && 'border' })} ref={forwardedRef}>
+ *         {children}
+ *       </Comp>
+ *     );
+ *   },
+ * );
+ * ```
+ */
+/** Symbol used to mark components created by `composable()` or `slottable()`. */
+const COMPOSABLE = Symbol.for('dxos.composable');
+
+export function slottable<E extends HTMLElement, P extends object = {}>(
+  render: (props: SlottableProps<P> & HTMLAttributes<E>, forwardedRef: ForwardedRef<E>) => ReactNode,
+): ForwardRefExoticComponent<SlottableProps<P> & RefAttributes<E>> {
+  const wrapped = (props: SlottableProps<P> & HTMLAttributes<E>, forwardedRef: ForwardedRef<E>) => {
+    let warn = false;
+    if (props.asChild) {
+      try {
+        const child = Children.only(props.children);
+        if (isValidElement(child) && typeof child.type !== 'string' && !(child.type as any)[COMPOSABLE]) {
+          warn = true;
+          log.warn('slot child is not composable; create it with composable() or slottable()', {
+            child: (child.type as any).displayName ?? (child.type as any).name,
+          });
+        }
+      } catch {
+        // Children.only throws if not exactly one child — Slot handles this.
+      }
+    }
+
+    const result = render(props, forwardedRef);
+    if (warn) {
+      return createElement('div', { role: 'none', className: 'dx-slot-warning' }, result);
+    }
+
+    return result;
+  };
+
+  const component = forwardRef(wrapped as any) as any;
+  (component as any)[COMPOSABLE] = true;
+  return component;
+}
+
+/**
+ * Factory for composable (leaf) components.
+ * The implementation receives full `HTMLAttributes<E>` so it can destructure `role`, `style`, etc.
+ * Consumers see only `ComposableProps<P>` — a narrow type exposing `classNames`, `className`,
+ * `children`, and the custom props `P`.
+ *
+ * For generic components, use `any` for the type parameter inside `composable` and
+ * cast the result to restore the generic signature for consumers.
+ *
+ * @example
+ * ```tsx
+ * const Leaf = composable<HTMLButtonElement>(({ children, ...props }, forwardedRef) => {
+ *   return (
+ *     <button {...composableProps(props, { classNames: 'btn' })} ref={forwardedRef}>
+ *       {children}
+ *     </button>
+ *   );
+ * });
+ * ```
+ */
+export function composable<E extends HTMLElement, P extends object = {}>(
+  render: (props: ComposableProps<P> & HTMLAttributes<E>, forwardedRef: ForwardedRef<E>) => ReactNode,
+): ForwardRefExoticComponent<ComposableProps<P> & RefAttributes<E>> {
+  const component = forwardRef(render as any) as any;
+  (component as any)[COMPOSABLE] = true;
+  return component;
+}

package/src/util/size.ts

@@ -0,0 +1,103 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { type CSSProperties } from 'react';
+
+import { type Size } from '@dxos/ui-types';
+
+import { mx } from '../util';
+
+// NOTE: Class names must be fully-specified string literals so Tailwind's static scanner can detect them.
+const sizeMap: Record<string, { w: string; h: string }> = {
+  0: { w: 'w-0', h: 'h-0' },
+  px: { w: 'w-px', h: 'h-px' },
+  0.5: { w: 'w-0.5', h: 'h-0.5' },
+  1: { w: 'w-1', h: 'h-1' },
+  1.5: { w: 'w-1.5', h: 'h-1.5' },
+  2: { w: 'w-2', h: 'h-2' },
+  2.5: { w: 'w-2.5', h: 'h-2.5' },
+  3: { w: 'w-3', h: 'h-3' },
+  3.5: { w: 'w-3.5', h: 'h-3.5' },
+  4: { w: 'w-4', h: 'h-4' },
+  5: { w: 'w-5', h: 'h-5' },
+  6: { w: 'w-6', h: 'h-6' },
+  7: { w: 'w-7', h: 'h-7' },
+  8: { w: 'w-8', h: 'h-8' },
+  9: { w: 'w-9', h: 'h-9' },
+  10: { w: 'w-10', h: 'h-10' },
+  11: { w: 'w-11', h: 'h-11' },
+  12: { w: 'w-12', h: 'h-12' },
+  14: { w: 'w-14', h: 'h-14' },
+  16: { w: 'w-16', h: 'h-16' },
+  20: { w: 'w-20', h: 'h-20' },
+  24: { w: 'w-24', h: 'h-24' },
+  28: { w: 'w-28', h: 'h-28' },
+  32: { w: 'w-32', h: 'h-32' },
+  36: { w: 'w-36', h: 'h-36' },
+  40: { w: 'w-40', h: 'h-40' },
+  44: { w: 'w-44', h: 'h-44' },
+  48: { w: 'w-48', h: 'h-48' },
+  52: { w: 'w-52', h: 'h-52' },
+  56: { w: 'w-56', h: 'h-56' },
+  60: { w: 'w-60', h: 'h-60' },
+  64: { w: 'w-64', h: 'h-64' },
+  72: { w: 'w-72', h: 'h-72' },
+  80: { w: 'w-80', h: 'h-80' },
+  96: { w: 'w-96', h: 'h-96' },
+};
+
+const SIZE_VALUES: Size[] = Object.keys(sizeMap).map((key) => (key === 'px' ? 'px' : (Number(key) as Size)));
+
+export const getHeight = (size: Size) => sizeMap[size]?.h;
+export const getWidth = (size: Size) => sizeMap[size]?.w;
+export const getSize = (size: Size) => mx(getHeight(size), getWidth(size));
+
+export const sizeValue = (size: Size): number => (size === 'px' ? 1 : size);
+export const sizeToRem = (size: Size): string => (size === 'px' ? '1px' : `${(size as number) * 0.25}rem`);
+
+export const iconSize = (size: Size | null): CSSProperties =>
+  ({ '--icon-size': size ? sizeToRem(size) : 'initial' }) as CSSProperties;
+
+/**
+ * Snaps an arbitrary numeric value to the nearest valid Tailwind size token.
+ *
+ * The function tries progressively coarser series in order until a match is found:
+ * 1. Exact match — returns the value as-is if it is already a valid `Size`.
+ * 2. Zero or negative — clamps to `0`.
+ * 3. Sub-half values (`< 0.5`) — maps to the `'px'` token (1 px).
+ * 4. Half-step series (0.5 increments, e.g. 1.5, 2.5 …).
+ * 5. Whole-number series (1, 2, 3 …).
+ * 6. Double series (even numbers: 2, 4, 6 …).
+ * 7. Quadruple series (multiples of 4: 4, 8, 12 …).
+ * 8. Falls back to `defaultSize` if no series matches.
+ *
+ * @param value - Numeric size to snap (in Tailwind spacing units, where 1 unit = 0.25 rem).
+ * @param defaultSize - Fallback `Size` token used when no series produces a valid match.
+ * @returns The nearest valid `Size` token.
+ */
+export const snapSize = (value: number, defaultSize: Size): Size => {
+  if (SIZE_VALUES.includes(value as Size)) {
+    return value as Size;
+  } else if (value <= 0) {
+    return 0;
+  } else if (value < 0.5) {
+    return 'px';
+  } else {
+    const wholeSeries = Math.floor(value);
+    const halfSeries = Math.floor(value * 2) / 2;
+    const doubleSeries = Math.floor(value / 2) * 2;
+    const quadrupleSeries = Math.floor(value / 4) * 4;
+    if (SIZE_VALUES.includes(halfSeries as Size)) {
+      return halfSeries as Size;
+    } else if (SIZE_VALUES.includes(wholeSeries as Size)) {
+      return wholeSeries as Size;
+    } else if (SIZE_VALUES.includes(doubleSeries as Size)) {
+      return doubleSeries as Size;
+    } else if (SIZE_VALUES.includes(quadrupleSeries as Size)) {
+      return quadrupleSeries as Size;
+    } else {
+      return defaultSize;
+    }
+  }
+};