@dxos/ui-theme 0.8.4-main.c85a9c8dae → 0.8.4-main.d05539e30a

package/src/util/hash-styles.ts

@@ -11,7 +11,7 @@ export type ColorStyles = {
   hue: Hue;
   fill: string; // -fill
   surface: string; // -surface
-  surfaceText: string; // -surface-text
+  foreground: string; // -foreground
   text: string; // -text
   border: string; // -border
 };
@@ -20,7 +20,7 @@ const neutral: ColorStyles = {
   hue: 'neutral',
   fill: 'bg-neutral-fill',
   surface: 'bg-neutral-surface',
-  surfaceText: 'text-neutral-surface-text',
+  foreground: 'text-neutral-foreground',
   text: 'text-neutral-text',
   border: 'border-neutral-border',
 };
@@ -32,7 +32,7 @@ const styles: ColorStyles[] = [
     hue: 'red',
     fill: 'bg-red-fill',
     surface: 'bg-red-surface',
-    surfaceText: 'text-red-surface-text',
+    foreground: 'text-red-foreground',
     text: 'text-red-text',
     border: 'border-red-border',
   },
@@ -40,7 +40,7 @@ const styles: ColorStyles[] = [
     hue: 'orange',
     fill: 'bg-orange-fill',
     surface: 'bg-orange-surface',
-    surfaceText: 'text-orange-surface-text',
+    foreground: 'text-orange-foreground',
     text: 'text-orange-text',
     border: 'border-orange-border',
   },
@@ -48,7 +48,7 @@ const styles: ColorStyles[] = [
     hue: 'amber',
     fill: 'bg-amber-fill',
     surface: 'bg-amber-surface',
-    surfaceText: 'text-amber-surface-text',
+    foreground: 'text-amber-foreground',
     text: 'text-amber-text',
     border: 'border-amber-border',
   },
@@ -56,7 +56,7 @@ const styles: ColorStyles[] = [
     hue: 'yellow',
     fill: 'bg-yellow-fill',
     surface: 'bg-yellow-surface',
-    surfaceText: 'text-yellow-surface-text',
+    foreground: 'text-yellow-foreground',
     text: 'text-yellow-text',
     border: 'border-yellow-border',
   },
@@ -64,7 +64,7 @@ const styles: ColorStyles[] = [
     hue: 'lime',
     fill: 'bg-lime-fill',
     surface: 'bg-lime-surface',
-    surfaceText: 'text-lime-surface-text',
+    foreground: 'text-lime-foreground',
     text: 'text-lime-text',
     border: 'border-lime-border',
   },
@@ -72,7 +72,7 @@ const styles: ColorStyles[] = [
     hue: 'green',
     fill: 'bg-green-fill',
     surface: 'bg-green-surface',
-    surfaceText: 'text-green-surface-text',
+    foreground: 'text-green-foreground',
     text: 'text-green-text',
     border: 'border-green-border',
   },
@@ -80,7 +80,7 @@ const styles: ColorStyles[] = [
     hue: 'emerald',
     fill: 'bg-emerald-fill',
     surface: 'bg-emerald-surface',
-    surfaceText: 'text-emerald-surface-text',
+    foreground: 'text-emerald-foreground',
     text: 'text-emerald-text',
     border: 'border-emerald-border',
   },
@@ -88,7 +88,7 @@ const styles: ColorStyles[] = [
     hue: 'teal',
     fill: 'bg-teal-fill',
     surface: 'bg-teal-surface',
-    surfaceText: 'text-teal-surface-text',
+    foreground: 'text-teal-foreground',
     text: 'text-teal-text',
     border: 'border-teal-border',
   },
@@ -96,7 +96,7 @@ const styles: ColorStyles[] = [
     hue: 'cyan',
     fill: 'bg-cyan-fill',
     surface: 'bg-cyan-surface',
-    surfaceText: 'text-cyan-surface-text',
+    foreground: 'text-cyan-foreground',
     text: 'text-cyan-text',
     border: 'border-cyan-border',
   },
@@ -104,7 +104,7 @@ const styles: ColorStyles[] = [
     hue: 'sky',
     fill: 'bg-sky-fill',
     surface: 'bg-sky-surface',
-    surfaceText: 'text-sky-surface-text',
+    foreground: 'text-sky-foreground',
     text: 'text-sky-text',
     border: 'border-sky-border',
   },
@@ -112,7 +112,7 @@ const styles: ColorStyles[] = [
     hue: 'blue',
     fill: 'bg-blue-fill',
     surface: 'bg-blue-surface',
-    surfaceText: 'text-blue-surface-text',
+    foreground: 'text-blue-foreground',
     text: 'text-blue-text',
     border: 'border-blue-border',
   },
@@ -120,7 +120,7 @@ const styles: ColorStyles[] = [
     hue: 'indigo',
     fill: 'bg-indigo-fill',
     surface: 'bg-indigo-surface',
-    surfaceText: 'text-indigo-surface-text',
+    foreground: 'text-indigo-foreground',
     text: 'text-indigo-text',
     border: 'border-indigo-border',
   },
@@ -128,7 +128,7 @@ const styles: ColorStyles[] = [
     hue: 'violet',
     fill: 'bg-violet-fill',
     surface: 'bg-violet-surface',
-    surfaceText: 'text-violet-surface-text',
+    foreground: 'text-violet-foreground',
     text: 'text-violet-text',
     border: 'border-violet-border',
   },
@@ -136,7 +136,7 @@ const styles: ColorStyles[] = [
     hue: 'purple',
     fill: 'bg-purple-fill',
     surface: 'bg-purple-surface',
-    surfaceText: 'text-purple-surface-text',
+    foreground: 'text-purple-foreground',
     text: 'text-purple-text',
     border: 'border-purple-border',
   },
@@ -144,7 +144,7 @@ const styles: ColorStyles[] = [
     hue: 'fuchsia',
     fill: 'bg-fuchsia-fill',
     surface: 'bg-fuchsia-surface',
-    surfaceText: 'text-fuchsia-surface-text',
+    foreground: 'text-fuchsia-foreground',
     text: 'text-fuchsia-text',
     border: 'border-fuchsia-border',
   },
@@ -152,7 +152,7 @@ const styles: ColorStyles[] = [
     hue: 'pink',
     fill: 'bg-pink-fill',
     surface: 'bg-pink-surface',
-    surfaceText: 'text-pink-surface-text',
+    foreground: 'text-pink-foreground',
     text: 'text-pink-text',
     border: 'border-pink-border',
   },
@@ -160,7 +160,7 @@ const styles: ColorStyles[] = [
     hue: 'rose',
     fill: 'bg-rose-fill',
     surface: 'bg-rose-surface',
-    surfaceText: 'text-rose-surface-text',
+    foreground: 'text-rose-foreground',
     text: 'text-rose-text',
     border: 'border-rose-border',
   },

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,9 +2,22 @@
 // Copyright 2022 DXOS.org
 //
 
+import {
+  Children,
+  createElement,
+  forwardRef,
+  type ForwardRefExoticComponent,
+  type ForwardedRef,
+  type HTMLAttributes,
+  isValidElement,
+  type ReactNode,
+  type RefAttributes,
+  CSSProperties,
+} from 'react';
 import { extendTailwindMerge, validators } from 'tailwind-merge';
 
-import { type ComposableProps } from '@dxos/ui-types';
+import { log } from '@dxos/log';
+import { ThemedClassName, type ComposableProps, type SlottableProps } from '@dxos/ui-types';
 
 type AdditionalClassGroups = 'density' | 'dx-focus-ring';
 
@@ -23,7 +36,6 @@ export const mx = extendTailwindMerge<AdditionalClassGroups>({
         'font-bold',
         'font-extrabold',
         'font-black',
-
         // Arbitrary numbers
         validators.isArbitraryNumber,
       ],
@@ -51,12 +63,111 @@ export const mx = extendTailwindMerge<AdditionalClassGroups>({
 });
 
 /**
- * Reconciles className properties from slot.
+ * 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`.
  */
-export const useComposableProps = (
-  { classNames, className, ...props }: Pick<ComposableProps, 'classNames' | 'className'>,
-  etc?: string,
+// TODO(burdon): Move to react-ui.
+export const composableProps = <P extends HTMLElement = HTMLElement>(
+  { className, classNames, role, style, ...props }: ComposableProps,
+  { classNames: defaultClassNames, ...defaults }: ThemedClassName<Partial<HTMLAttributes<P>>> | undefined = {},
 ) => ({
-  className: mx(etc, classNames, className),
-  props,
+  // Default props.
+  ...(defaults as object),
+
+  // Spread supplied props.
+  ...props,
+
+  // Prefer explicit role, then defaults role, then 'none'.
+  role: role ?? defaults.role ?? 'none',
+
+  // Merge styles.
+  style: { ...defaults.style, ...style } as CSSProperties,
+
+  // Compose classnames.
+  className: mx(defaultClassNames, className, classNames),
 });
+
+/** Symbol used to mark components created by `composable()` or `slottable()`. */
+const COMPOSABLE = Symbol.for('dxos.composable');
+
+/**
+ * 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>
+ *     );
+ *   },
+ * );
+ * ```
+ */
+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;
+    }
+  }
+};