@pickle-ui/react 0.0.0-stage → 1.0.0-beta.3

package/src/entries/table.ts

@@ -0,0 +1,11 @@
+export { Table } from '../components/Table';
+export type {
+  TableBodyProps,
+  TableCaptionProps,
+  TableCellProps,
+  TableFooterProps,
+  TableHeaderProps,
+  TableHeadProps,
+  TableProps,
+  TableRowProps,
+} from '../components/Table';

package/src/entries/text.ts

@@ -0,0 +1,2 @@
+export { Text, textVariants } from '../components/Text';
+export type { TextProps } from '../components/Text';

package/src/entries/textarea.ts

@@ -0,0 +1,2 @@
+export { Textarea } from '../components/form/Textarea';
+export type { TextareaProps } from '../components/form/Textarea';

package/src/entries/theme.ts

@@ -0,0 +1,8 @@
+export { createTheme, themeToCss } from '../lib/theme';
+export type {
+  Theme,
+  ThemeCssOptions,
+  ThemeFonts,
+  ThemeOptions,
+  ThemeVariables,
+} from '../lib/theme';

package/src/entries/toast.ts

@@ -0,0 +1,2 @@
+export { Toast } from '../components/Toast';
+export type { ToastProviderProps } from '../components/Toast';

package/src/entries/tooltip.ts

@@ -0,0 +1,7 @@
+export { Tooltip } from '../components/Tooltip';
+export type {
+  TooltipContentProps,
+  TooltipProps,
+  TooltipProviderProps,
+  TooltipTriggerProps,
+} from '../components/Tooltip';

package/src/entries/x-stack.ts

@@ -0,0 +1,2 @@
+export { XStack } from '../components/XStack';
+export type { XStackProps } from '../components/XStack';

package/src/entries/y-stack.ts

@@ -0,0 +1,2 @@
+export { YStack } from '../components/YStack';
+export type { YStackProps } from '../components/YStack';

package/src/hooks/use-as-ref.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+import { useIsomorphicLayoutEffect } from '@/hooks/use-isomorphic-layout-effect';
+
+function useAsRef<T>(props: T) {
+  const ref = React.useRef<T>(props);
+
+  useIsomorphicLayoutEffect(() => {
+    ref.current = props;
+  });
+
+  return ref;
+}
+
+export { useAsRef };

package/src/hooks/use-isomorphic-layout-effect.ts

@@ -0,0 +1,6 @@
+import * as React from 'react';
+
+const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
+
+export { useIsomorphicLayoutEffect };

package/src/hooks/use-lazy-ref.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+
+function useLazyRef<T>(fn: () => T) {
+  const ref = React.useRef<null | T>(null);
+
+  if (ref.current === null) {
+    ref.current = fn();
+  }
+
+  return ref as React.RefObject<T>;
+}
+
+export { useLazyRef };

package/src/index.ts

@@ -0,0 +1,38 @@
+// The public API is the union of the subpath entries in ./entries: add a
+// component there and re-export it here (see "Public API" in AGENTS.md).
+export * from './entries/alert';
+export * from './entries/alert-dialog';
+export * from './entries/avatar';
+export * from './entries/badge';
+export * from './entries/button';
+export * from './entries/card';
+export * from './entries/checkbox';
+export * from './entries/cn';
+export * from './entries/color-picker';
+export * from './entries/combobox';
+export * from './entries/dialog';
+export * from './entries/flex';
+export * from './entries/form';
+export * from './entries/grid';
+export * from './entries/group';
+export * from './entries/input';
+export * from './entries/input-group';
+export * from './entries/menu';
+export * from './entries/popover';
+export * from './entries/progress';
+export * from './entries/radio-group';
+export * from './entries/scroll-area';
+export * from './entries/select';
+export * from './entries/separator';
+export * from './entries/sidebar';
+export * from './entries/slider';
+export * from './entries/spinner';
+export * from './entries/switch';
+export * from './entries/table';
+export * from './entries/text';
+export * from './entries/textarea';
+export * from './entries/theme';
+export * from './entries/toast';
+export * from './entries/tooltip';
+export * from './entries/x-stack';
+export * from './entries/y-stack';

package/src/lib/color.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  colorToString,
+  hexToRgb,
+  hslToRgb,
+  hsvToRgb,
+  parseColorString,
+  rgbToHex,
+  rgbToHsl,
+  rgbToHsv,
+} from './color';
+
+describe('hex <-> rgb', () => {
+  it('parses a primary hex to rgb', () => {
+    expect(hexToRgb('#ff0000')).toEqual({ a: 1, b: 0, g: 0, r: 255 });
+  });
+
+  it('applies an explicit alpha', () => {
+    expect(hexToRgb('#ff0000', 0.5)).toEqual({ a: 0.5, b: 0, g: 0, r: 255 });
+  });
+
+  it('falls back to black for an unparseable string', () => {
+    expect(hexToRgb('not-a-color')).toEqual({ a: 1, b: 0, g: 0, r: 0 });
+  });
+
+  it('serializes rgb back to hex', () => {
+    expect(rgbToHex({ a: 1, b: 0, g: 0, r: 255 })).toBe('#ff0000');
+  });
+});
+
+describe('rgb <-> hsv', () => {
+  it('converts a primary to hsv', () => {
+    expect(rgbToHsv({ a: 1, b: 0, g: 0, r: 255 })).toEqual({
+      a: 1,
+      h: 0,
+      s: 100,
+      v: 100,
+    });
+  });
+
+  it('converts hsv green back to rgb', () => {
+    expect(hsvToRgb({ a: 1, h: 120, s: 100, v: 100 })).toEqual({
+      a: 1,
+      b: 0,
+      g: 255,
+      r: 0,
+    });
+  });
+
+  // Documents CURRENT behavior: achromatic colors report hue 0 (red).
+  // Plan 004 changes this to preserve a caller-supplied hue. When 004 lands,
+  // this assertion is expected to be updated there.
+  it('reports hue 0 for white (achromatic)', () => {
+    expect(rgbToHsv({ a: 1, b: 255, g: 255, r: 255 })).toEqual({
+      a: 1,
+      h: 0,
+      s: 0,
+      v: 100,
+    });
+  });
+});
+
+describe('rgb <-> hsl', () => {
+  it('converts a primary to hsl', () => {
+    expect(rgbToHsl({ a: 1, b: 0, g: 0, r: 255 })).toEqual({
+      h: 0,
+      l: 50,
+      s: 100,
+    });
+  });
+
+  it('converts hsl green back to rgb', () => {
+    expect(hslToRgb({ h: 120, l: 50, s: 100 })).toEqual({
+      a: 1,
+      b: 0,
+      g: 255,
+      r: 0,
+    });
+  });
+});
+
+describe('parseColorString', () => {
+  it('parses an rgb() string', () => {
+    expect(parseColorString('rgb(255, 0, 0)')).toEqual({
+      a: 1,
+      b: 0,
+      g: 0,
+      r: 255,
+    });
+  });
+
+  it('parses an hsb() string (handled by the custom parser)', () => {
+    expect(parseColorString('hsb(120, 100%, 100%)')).toEqual({
+      a: 1,
+      b: 0,
+      g: 255,
+      r: 0,
+    });
+  });
+
+  it('returns null for an unparseable string', () => {
+    expect(parseColorString('definitely not a color')).toBeNull();
+  });
+});
+
+describe('colorToString', () => {
+  it('formats opaque rgb without the alpha channel', () => {
+    expect(colorToString({ a: 1, b: 0, g: 0, r: 255 }, 'rgb')).toBe(
+      'rgb(255, 0, 0)',
+    );
+  });
+
+  it('formats translucent rgb with the alpha channel', () => {
+    expect(colorToString({ a: 0.5, b: 0, g: 0, r: 255 }, 'rgb')).toBe(
+      'rgba(255, 0, 0, 0.5)',
+    );
+  });
+
+  it('defaults to hex', () => {
+    expect(colorToString({ a: 1, b: 0, g: 0, r: 0 })).toBe('#000000');
+  });
+});
+
+describe('rgbToHsv hue preservation', () => {
+  it('uses the fallback hue for an achromatic color', () => {
+    // White has no intrinsic hue; without a fallback it reports 0.
+    expect(rgbToHsv({ a: 1, b: 255, g: 255, r: 255 }, 200)).toEqual({
+      a: 1,
+      h: 200,
+      s: 0,
+      v: 100,
+    });
+  });
+
+  it('ignores the fallback when the color has a real hue', () => {
+    expect(rgbToHsv({ a: 1, b: 0, g: 255, r: 0 }, 200)).toEqual({
+      a: 1,
+      h: 120,
+      s: 100,
+      v: 100,
+    });
+  });
+
+  it('still defaults to hue 0 with no fallback (backward compatible)', () => {
+    expect(rgbToHsv({ a: 1, b: 128, g: 128, r: 128 })).toMatchObject({ h: 0 });
+  });
+});

package/src/lib/color.ts

@@ -0,0 +1,193 @@
+/**
+ * Color helpers for the color picker.
+ *
+ * culori performs every color-space conversion and string parse. The functions
+ * here are thin adapters that translate between culori's normalized shape
+ * (`{ mode, r/g/b: 0–1, alpha: 0–1 }`) and the integer/percentage shape the UI
+ * works in (`ColorValue` with 0–255 channels, HSL/HSV in degrees/percent), plus
+ * rounding and null-hue handling for greys.
+ */
+
+/* eslint-disable perfectionist/sort-objects, perfectionist/sort-object-types, perfectionist/sort-interfaces, perfectionist/sort-modules, perfectionist/sort-switch-case -- color values read best in their conventional order (RGBA/HSVA channels, culori's mode-first shape, rgb↔x conversion pairs, format precedence) rather than alphabetically. */
+
+import { converter, formatHex, type Hsv, parse, type Rgb } from 'culori';
+
+export const colorFormats = ['hex', 'rgb', 'hsl', 'hsb'] as const;
+
+export type ColorFormat = (typeof colorFormats)[number];
+
+export interface ColorValue {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export interface HSVColorValue {
+  h: number;
+  s: number;
+  v: number;
+  a: number;
+}
+
+const toRgb = converter('rgb');
+const toHsl = converter('hsl');
+const toHsv = converter('hsv');
+
+function clamp(value: number, min: number, max: number) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function alphaToValue(alpha: number | undefined) {
+  return clamp(alpha ?? 1, 0, 1);
+}
+
+function parseAlphaValue(value: string | undefined, isPercent?: string) {
+  if (!value) return 1;
+
+  const alpha = Number.parseFloat(value);
+  return alphaToValue(isPercent ? alpha / 100 : alpha);
+}
+
+function toCuloriRgb(color: ColorValue): Rgb {
+  return {
+    mode: 'rgb',
+    r: color.r / 255,
+    g: color.g / 255,
+    b: color.b / 255,
+    alpha: color.a,
+  };
+}
+
+function fromCuloriRgb(color: Rgb): ColorValue {
+  return {
+    r: Math.round(clamp(color.r, 0, 1) * 255),
+    g: Math.round(clamp(color.g, 0, 1) * 255),
+    b: Math.round(clamp(color.b, 0, 1) * 255),
+    a: alphaToValue(color.alpha),
+  };
+}
+
+/** culori does not parse the `hsb()`/`hsba()` notation, so handle it ourselves. */
+function parseHsbString(value: string): Hsv | null {
+  const numberPattern = String.raw`([+-]?(?:\d+\.?\d*|\.\d+))`;
+  const hsbMatch = new RegExp(
+    String.raw`^hsba?\(\s*${numberPattern}(?:deg)?(?:\s*,\s*|\s+)${numberPattern}%(?:\s*,\s*|\s+)${numberPattern}%(?:\s*(?:,|\/)\s*${numberPattern}(%)?)?\s*\)$`,
+    'i',
+  ).exec(value);
+
+  if (!hsbMatch) return null;
+
+  return {
+    mode: 'hsv',
+    h: Number.parseFloat(hsbMatch[1] ?? '0'),
+    s: clamp(Number.parseFloat(hsbMatch[2] ?? '0') / 100, 0, 1),
+    v: clamp(Number.parseFloat(hsbMatch[3] ?? '0') / 100, 0, 1),
+    alpha: parseAlphaValue(hsbMatch[4], hsbMatch[5]),
+  };
+}
+
+export function hexToRgb(hex: string, alpha?: number): ColorValue {
+  const color = parse(hex);
+  const rgb = color ? toRgb(color) : undefined;
+
+  return rgb
+    ? { ...fromCuloriRgb(rgb), a: alpha ?? 1 }
+    : { r: 0, g: 0, b: 0, a: alpha ?? 1 };
+}
+
+export function isColorEqual(a: ColorValue, b: ColorValue) {
+  return a.r === b.r && a.g === b.g && a.b === b.b && a.a === b.a;
+}
+
+export function isHsvEqual(a: HSVColorValue, b: HSVColorValue) {
+  return a.h === b.h && a.s === b.s && a.v === b.v && a.a === b.a;
+}
+
+export function rgbToHex(color: ColorValue): string {
+  return formatHex(toCuloriRgb(color)) ?? '#000000';
+}
+
+export function rgbToHsv(color: ColorValue, fallbackHue = 0): HSVColorValue {
+  const hsv = toHsv(toCuloriRgb(color));
+
+  return {
+    h: Math.round(hsv.h ?? fallbackHue),
+    s: Math.round(hsv.s * 100),
+    v: Math.round(hsv.v * 100),
+    a: alphaToValue(hsv.alpha),
+  };
+}
+
+export function hsvToRgb(hsv: HSVColorValue): ColorValue {
+  return fromCuloriRgb(
+    toRgb({
+      mode: 'hsv',
+      h: hsv.h,
+      s: hsv.s / 100,
+      v: hsv.v / 100,
+      alpha: hsv.a,
+    }),
+  );
+}
+
+export function rgbToHsl(color: ColorValue) {
+  const hsl = toHsl(toCuloriRgb(color));
+
+  return {
+    h: Math.round(hsl.h ?? 0),
+    s: Math.round(hsl.s * 100),
+    l: Math.round(hsl.l * 100),
+  };
+}
+
+export function hslToRgb(
+  hsl: { h: number; s: number; l: number },
+  alpha = 1,
+): ColorValue {
+  return fromCuloriRgb(
+    toRgb({
+      mode: 'hsl',
+      h: hsl.h,
+      s: hsl.s / 100,
+      l: hsl.l / 100,
+      alpha,
+    }),
+  );
+}
+
+export function colorToString(
+  color: ColorValue,
+  format: ColorFormat = 'hex',
+): string {
+  switch (format) {
+    case 'hex':
+      return rgbToHex(color);
+    case 'rgb':
+      return color.a < 1
+        ? `rgba(${color.r}, ${color.g}, ${color.b}, ${color.a})`
+        : `rgb(${color.r}, ${color.g}, ${color.b})`;
+    case 'hsl': {
+      const hsl = rgbToHsl(color);
+      return color.a < 1
+        ? `hsla(${hsl.h}, ${hsl.s}%, ${hsl.l}%, ${color.a})`
+        : `hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`;
+    }
+    case 'hsb': {
+      const hsv = rgbToHsv(color);
+      return color.a < 1
+        ? `hsba(${hsv.h}, ${hsv.s}%, ${hsv.v}%, ${color.a})`
+        : `hsb(${hsv.h}, ${hsv.s}%, ${hsv.v}%)`;
+    }
+    default:
+      return rgbToHex(color);
+  }
+}
+
+export function parseColorString(value: string): ColorValue | null {
+  const trimmed = value.trim();
+  const color = parseHsbString(trimmed) ?? parse(trimmed);
+  const rgb = color ? toRgb(color) : undefined;
+
+  return rgb ? fromCuloriRgb(rgb) : null;
+}

package/src/lib/compose-refs.ts

@@ -0,0 +1,63 @@
+import * as React from 'react';
+
+type PossibleRef<T> = React.Ref<T> | undefined;
+
+/**
+ * A utility to compose multiple refs together
+ * Accepts callback refs and RefObject(s)
+ */
+function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
+  return (node) => {
+    let hasCleanup = false;
+    const cleanups = refs.map((ref) => {
+      const cleanup = setRef(ref, node);
+      if (!hasCleanup && typeof cleanup === 'function') {
+        hasCleanup = true;
+      }
+      return cleanup;
+    });
+
+    // React <19 will log an error to the console if a callback ref returns a
+    // value. We don't use ref cleanups internally so this will only happen if a
+    // user's ref callback returns a value, which we only expect if they are
+    // using the cleanup functionality added in React 19.
+    if (hasCleanup) {
+      return () => {
+        for (let i = 0; i < cleanups.length; i++) {
+          const cleanup = cleanups[i];
+          if (typeof cleanup === 'function') {
+            cleanup();
+          } else {
+            setRef(refs[i], null);
+          }
+        }
+      };
+    }
+  };
+}
+
+/**
+ * Set a given ref to a given value
+ * This utility takes care of different types of refs: callback refs and RefObject(s)
+ */
+function setRef<T>(ref: PossibleRef<T>, value: T) {
+  if (typeof ref === 'function') {
+    return ref(value);
+  }
+
+  if (ref !== null && ref !== undefined) {
+    ref.current = value;
+  }
+}
+
+/**
+ * A custom hook that composes multiple refs
+ * Accepts callback refs and RefObject(s)
+ */
+function useComposedRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
+  // biome-ignore lint/correctness/useExhaustiveDependencies: we want to memoize by all values
+  // eslint-disable-next-line react-hooks/exhaustive-deps, react-hooks/use-memo -- memoize by every ref value; the spread `refs` array is the intended dependency list
+  return React.useCallback(composeRefs(...refs), refs); // react-doctor-disable-line react-doctor/exhaustive-deps -- same intentional memo: the dependency list is the spread `refs` array on purpose
+}
+
+export { composeRefs, useComposedRefs };

package/src/lib/theme.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+
+import { createTheme, themeToCss } from './theme';
+
+describe('createTheme', () => {
+  it('derives primary tokens for both schemes', () => {
+    const theme = createTheme({ primary: '#16a34a' });
+
+    expect(theme.light['--primary']).toMatch(/^oklch\(/);
+    expect(theme.dark['--primary']).toMatch(/^oklch\(/);
+    expect(theme.light['--primary']).not.toBe(theme.dark['--primary']);
+    expect(theme.light['--sidebar-primary']).toBe(theme.light['--primary']);
+  });
+
+  it('picks a readable foreground for light and dark fills', () => {
+    const onDarkFill = createTheme({ primary: '#1e3a8a' });
+    const onLightFill = createTheme({ primary: '#fde047' });
+
+    expect(onDarkFill.light['--primary-foreground']).toBe('oklch(1 0 0)');
+    expect(onLightFill.light['--primary-foreground']).not.toBe('oklch(1 0 0)');
+  });
+
+  it('uses primaryDark as given and passes radius and fonts through', () => {
+    const theme = createTheme({
+      fonts: { mono: 'Menlo', sans: 'Inter' },
+      primary: 'rebeccapurple',
+      primaryDark: 'oklch(0.8 0.1 300)',
+      radius: '1rem',
+    });
+
+    expect(theme.dark['--primary']).toBe('oklch(0.8 0.1 300)');
+    expect(theme.light['--radius']).toBe('1rem');
+    expect(theme.dark['--radius']).toBe('1rem');
+    expect(theme.light['--font-sans']).toBe('Inter');
+    expect(theme.light['--font-mono']).toBe('Menlo');
+    expect(theme.light['--font-heading']).toBeUndefined();
+  });
+
+  it('rejects colors it cannot parse', () => {
+    expect(() => createTheme({ primary: 'not-a-color' })).toThrow(
+      /not a valid CSS color/,
+    );
+  });
+});
+
+describe('themeToCss', () => {
+  it('serializes both schemes under their selectors', () => {
+    const css = themeToCss(createTheme({ primary: '#000', radius: '4px' }));
+
+    expect(css).toMatch(/^:root \{\n {2}--radius: 4px;\n/);
+    expect(css).toContain('\n.dark {\n');
+    expect(css).toContain('--primary-foreground: oklch(1 0 0);');
+  });
+
+  it('accepts custom selectors', () => {
+    const css = themeToCss(createTheme({ primary: '#000' }), {
+      darkSelector: '[data-theme="dark"]',
+      lightSelector: 'html',
+    });
+
+    expect(css.startsWith('html {')).toBe(true);
+    expect(css).toContain('[data-theme="dark"] {');
+  });
+});