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

package/src/lib/theme.ts

@@ -0,0 +1,143 @@
+/**
+ * Theme generator: derives Pickle's brand-dependent tokens from a single
+ * primary color so consumers can theme the library without hand-writing CSS
+ * variables. Tokens that do not depend on the brand (neutrals, status colors)
+ * keep the values from `@pickle-ui/react/theme.css`.
+ */
+
+import {
+  clampChroma,
+  converter,
+  formatCss,
+  type Oklch,
+  parse,
+  wcagContrast,
+} from 'culori';
+
+type Theme = {
+  dark: ThemeVariables;
+  light: ThemeVariables;
+};
+
+type ThemeCssOptions = {
+  darkSelector?: string;
+  lightSelector?: string;
+};
+
+type ThemeFonts = {
+  heading?: string;
+  mono?: string;
+  sans?: string;
+};
+
+type ThemeOptions = {
+  /** Font stacks, written to `--font-sans`, `--font-heading` and `--font-mono`. */
+  fonts?: ThemeFonts;
+  /** Brand color in any CSS notation (hex, rgb, hsl, oklch, …). */
+  primary: string;
+  /** Brand color for the dark scheme. Defaults to a lighter version of `primary`. */
+  primaryDark?: string;
+  /** Base radius, e.g. `'0.5rem'`. Every `rounded-*` scale derives from it. */
+  radius?: string;
+};
+
+type ThemeVariables = Record<`--${string}`, string>;
+
+const toOklch = converter('oklch');
+
+const LIGHT_FOREGROUND: Oklch = { c: 0, h: 0, l: 1, mode: 'oklch' };
+const DARK_FOREGROUND: Oklch = { c: 0.006, h: 285.9, l: 0.21, mode: 'oklch' };
+
+/**
+ * Build the light and dark token sets for a brand color. Apply the result
+ * with `themeToCss` in a stylesheet, or spread `theme.light` / `theme.dark`
+ * as the `style` of a wrapper element.
+ */
+export function createTheme(options: ThemeOptions): Theme {
+  const primary = parseColor(options.primary, 'primary');
+  const primaryDark = options.primaryDark
+    ? parseColor(options.primaryDark, 'primaryDark')
+    : lightenForDark(primary);
+  const shared = sharedVariables(options);
+
+  return {
+    dark: { ...shared, ...brandVariables(primaryDark) },
+    light: { ...shared, ...brandVariables(primary) },
+  };
+}
+
+/** Serialize a theme as CSS rules for the light and dark selectors. */
+export function themeToCss(
+  theme: Theme,
+  { darkSelector = '.dark', lightSelector = ':root' }: ThemeCssOptions = {},
+): string {
+  const block = (selector: string, variables: ThemeVariables) =>
+    `${selector} {\n${Object.entries(variables)
+      .map(([name, value]) => `  ${name}: ${value};`)
+      .join('\n')}\n}`;
+
+  return `${block(lightSelector, theme.light)}\n\n${block(darkSelector, theme.dark)}\n`;
+}
+
+function brandVariables(primary: Oklch): ThemeVariables {
+  const foreground = foregroundFor(primary);
+
+  return {
+    '--primary': format(primary),
+    '--primary-foreground': format(foreground),
+    '--ring': format({ ...primary, c: primary.c * 0.6 }),
+    '--sidebar-primary': format(primary),
+    '--sidebar-primary-foreground': format(foreground),
+    '--sidebar-ring': format({ ...primary, c: primary.c * 0.6 }),
+  };
+}
+
+/** White or near-black, whichever reads better on the given fill. */
+function foregroundFor(fill: Oklch) {
+  return wcagContrast(fill, LIGHT_FOREGROUND) >=
+    wcagContrast(fill, DARK_FOREGROUND)
+    ? LIGHT_FOREGROUND
+    : DARK_FOREGROUND;
+}
+
+function format(color: Oklch) {
+  return formatCss(clampChroma(color, 'oklch'));
+}
+
+/** Lift a brand color so it stays vivid on dark surfaces. */
+function lightenForDark(color: Oklch): Oklch {
+  return {
+    ...color,
+    c: color.c * 0.92,
+    l: Math.min(Math.max(color.l + 0.12, 0.6), 0.85),
+  };
+}
+
+function parseColor(value: string, name: string): Oklch {
+  const color = parse(value);
+
+  if (!color) {
+    throw new Error(`createTheme: ${name} is not a valid CSS color: ${value}`);
+  }
+
+  return toOklch(color);
+}
+
+function sharedVariables({ fonts, radius }: ThemeOptions): ThemeVariables {
+  const variables: ThemeVariables = {};
+
+  if (radius) variables['--radius'] = radius;
+  if (fonts?.sans) variables['--font-sans'] = fonts.sans;
+  if (fonts?.heading) variables['--font-heading'] = fonts.heading;
+  if (fonts?.mono) variables['--font-mono'] = fonts.mono;
+
+  return variables;
+}
+
+export type {
+  Theme,
+  ThemeCssOptions,
+  ThemeFonts,
+  ThemeOptions,
+  ThemeVariables,
+};

package/src/lib/utils.ts

@@ -0,0 +1,25 @@
+import { type ClassValue, clsx } from 'clsx';
+import { extendTailwindMerge } from 'tailwind-merge';
+
+/**
+ * Teaches tailwind-merge Pickle's theme scales: `text-body`, `text-h1`, … are
+ * font sizes, so they must not be mistaken for text colors and dropped next
+ * to one.
+ */
+const twMerge = extendTailwindMerge({
+  extend: {
+    theme: {
+      text: ['body', 'code', 'h1', 'h2', 'h3', 'h4', 'lead', 'small'],
+    },
+  },
+});
+
+/**
+ * Per-slot class overrides for components that render several parts from a
+ * single props object. Keys match the suffix of each part's `data-slot`.
+ */
+export type SlotClassNames<Slot extends string> = Partial<Record<Slot, string>>;
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/public-api.test.ts

@@ -0,0 +1,74 @@
+import { readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+import * as publicApi from './index';
+
+// Guards the rules of "Public API" in AGENTS.md: one value per component,
+// parts reached through the compound, and entries that mirror the index.
+
+const NON_COMPONENT_EXPORTS = [
+  'badgeVariants',
+  'buttonVariants',
+  'cn',
+  'createTheme',
+  'textVariants',
+  'themeToCss',
+];
+
+const entriesDir = join(dirname(fileURLToPath(import.meta.url)), 'entries');
+const entryNames = readdirSync(entriesDir)
+  .filter((file) => file.endsWith('.ts') && !file.endsWith('.test.ts'))
+  .map((file) => file.replace(/\.ts$/, ''));
+
+const exportNames = Object.keys(publicApi).sort();
+
+describe('public API', () => {
+  it('only exports components and the allowed helpers', () => {
+    const unexpected = exportNames.filter(
+      (name) =>
+        !NON_COMPONENT_EXPORTS.includes(name) && !/^[A-Z][A-Za-z]*$/.test(name),
+    );
+
+    expect(unexpected).toEqual([]);
+  });
+
+  it('does not export primitives or roots under their own names', () => {
+    expect(
+      exportNames.filter((name) => /(Primitive|Root)$/.test(name)),
+    ).toEqual([]);
+  });
+
+  it('does not export compound parts under parallel names', () => {
+    const parallel = exportNames.flatMap((name) => {
+      const value = publicApi[name as keyof typeof publicApi];
+
+      if (typeof value !== 'function') {
+        return [];
+      }
+
+      return Object.keys(value)
+        .map((part) => `${name}${part}`)
+        .filter((partName) => exportNames.includes(partName));
+    });
+
+    expect(parallel).toEqual([]);
+  });
+
+  it('exports from the entries exactly what the index exports', async () => {
+    const entryExports = new Set<string>();
+
+    for (const name of entryNames) {
+      const module = (await import(
+        pathToFileURL(join(entriesDir, `${name}.ts`)).href
+      )) as Record<string, unknown>;
+
+      for (const key of Object.keys(module)) {
+        entryExports.add(key);
+      }
+    }
+
+    expect([...entryExports].sort()).toEqual(exportNames);
+  });
+});

package/src/styles.css

@@ -0,0 +1,2 @@
+@import './theme.css';
+@import './base.css';

package/src/test-setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';

package/src/theme.css

@@ -0,0 +1,195 @@
+/**
+ * Pickle design tokens: Tailwind theme mapping plus light and dark values.
+ * Import this file alone to reuse the tokens without Pickle's base styles,
+ * or override any variable after importing `@pickle-ui/react/styles.css`.
+ */
+
+@theme inline {
+  --font-sans: var(--font-sans);
+  --font-heading: var(--font-sans);
+  --font-mono: var(--font-mono);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-destructive-subtle: var(--destructive-subtle);
+  --color-destructive-subtle-foreground: var(--destructive-subtle-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+  --color-info-subtle: var(--info-subtle);
+  --color-info-subtle-foreground: var(--info-subtle-foreground);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-success-subtle: var(--success-subtle);
+  --color-success-subtle-foreground: var(--success-subtle-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-warning-subtle: var(--warning-subtle);
+  --color-warning-subtle-foreground: var(--warning-subtle-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --animate-skeleton: skeleton 2s -1s infinite linear;
+  @keyframes skeleton {
+    to {
+      background-position: -200% 0;
+    }
+  }
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: var(--color-white);
+  --foreground: var(--color-neutral-800);
+  --card: var(--color-white);
+  --card-foreground: var(--color-neutral-800);
+  --popover: var(--color-white);
+  --popover-foreground: var(--color-neutral-800);
+  --primary: var(--color-neutral-800);
+  --primary-foreground: var(--color-neutral-50);
+  --secondary: --alpha(var(--color-black) / 4%);
+  --secondary-foreground: var(--color-neutral-800);
+  --muted: --alpha(var(--color-black) / 4%);
+  --muted-foreground: color-mix(
+    in srgb,
+    var(--color-neutral-500) 90%,
+    var(--color-black)
+  );
+  --accent: --alpha(var(--color-black) / 4%);
+  --accent-foreground: var(--color-neutral-800);
+  --destructive: var(--color-red-500);
+  --destructive-foreground: var(--color-white);
+  --destructive-subtle: --alpha(var(--destructive) / 8%);
+  --destructive-subtle-foreground: var(--color-red-700);
+  --info: var(--color-blue-500);
+  --info-foreground: var(--color-white);
+  --info-subtle: --alpha(var(--info) / 8%);
+  --info-subtle-foreground: var(--color-blue-700);
+  --success: var(--color-emerald-500);
+  --success-foreground: var(--color-white);
+  --success-subtle: --alpha(var(--success) / 8%);
+  --success-subtle-foreground: var(--color-emerald-700);
+  --warning: var(--color-amber-500);
+  --warning-foreground: var(--color-amber-950);
+  --warning-subtle: --alpha(var(--warning) / 8%);
+  --warning-subtle-foreground: var(--color-amber-700);
+  --border: --alpha(var(--color-black) / 8%);
+  --input: --alpha(var(--color-black) / 10%);
+  --ring: var(--color-neutral-400);
+  --chart-1: var(--color-blue-600);
+  --chart-2: var(--color-emerald-600);
+  --chart-3: var(--color-amber-600);
+  --chart-4: var(--color-purple-600);
+  --chart-5: var(--color-rose-600);
+  --sidebar: var(--color-neutral-50);
+  --sidebar-foreground: color-mix(
+    in srgb,
+    var(--color-neutral-800) 64%,
+    var(--sidebar)
+  );
+  --sidebar-primary: var(--color-neutral-800);
+  --sidebar-primary-foreground: var(--color-neutral-50);
+  --sidebar-accent: --alpha(var(--color-black) / 4%);
+  --sidebar-accent-foreground: var(--color-neutral-800);
+  --sidebar-border: --alpha(var(--color-black) / 6%);
+  --sidebar-ring: var(--color-neutral-400);
+}
+
+.dark {
+  --background: color-mix(
+    in srgb,
+    var(--color-neutral-950) 96%,
+    var(--color-white)
+  );
+  --foreground: var(--color-neutral-100);
+  --card: color-mix(in srgb, var(--background) 98%, var(--color-white));
+  --card-foreground: var(--color-neutral-100);
+  --popover: color-mix(in srgb, var(--background) 96%, var(--color-white));
+  --popover-foreground: var(--color-neutral-100);
+  --primary: var(--color-neutral-100);
+  --primary-foreground: var(--color-neutral-800);
+  --secondary: --alpha(var(--color-white) / 4%);
+  --secondary-foreground: var(--color-neutral-100);
+  --muted: --alpha(var(--color-white) / 4%);
+  --muted-foreground: color-mix(
+    in srgb,
+    var(--color-neutral-500) 90%,
+    var(--color-white)
+  );
+  --accent: --alpha(var(--color-white) / 4%);
+  --accent-foreground: var(--color-neutral-100);
+  --destructive: color-mix(
+    in srgb,
+    var(--color-red-500) 90%,
+    var(--color-white)
+  );
+  --destructive-foreground: var(--color-white);
+  --destructive-subtle: --alpha(var(--destructive) / 16%);
+  --destructive-subtle-foreground: var(--color-red-400);
+  --info: var(--color-blue-500);
+  --info-foreground: var(--color-white);
+  --info-subtle: --alpha(var(--info) / 16%);
+  --info-subtle-foreground: var(--color-blue-400);
+  --success: var(--color-emerald-500);
+  --success-foreground: var(--color-white);
+  --success-subtle: --alpha(var(--success) / 16%);
+  --success-subtle-foreground: var(--color-emerald-400);
+  --warning: var(--color-amber-500);
+  --warning-foreground: var(--color-amber-950);
+  --warning-subtle: --alpha(var(--warning) / 16%);
+  --warning-subtle-foreground: var(--color-amber-400);
+  --border: --alpha(var(--color-white) / 6%);
+  --input: --alpha(var(--color-white) / 8%);
+  --ring: var(--color-neutral-500);
+  --chart-1: var(--color-blue-500);
+  --chart-2: var(--color-emerald-500);
+  --chart-3: var(--color-amber-500);
+  --chart-4: var(--color-purple-500);
+  --chart-5: var(--color-rose-500);
+  --sidebar: color-mix(
+    in srgb,
+    var(--color-neutral-950) 97%,
+    var(--color-white)
+  );
+  --sidebar-foreground: color-mix(
+    in srgb,
+    var(--color-neutral-100) 64%,
+    var(--sidebar)
+  );
+  --sidebar-primary: var(--color-neutral-100);
+  --sidebar-primary-foreground: var(--color-neutral-800);
+  --sidebar-accent: --alpha(var(--color-white) / 4%);
+  --sidebar-accent-foreground: var(--color-neutral-100);
+  --sidebar-border: --alpha(var(--color-white) / 5%);
+  --sidebar-ring: var(--color-neutral-500);
+}