@yarcl/react 0.1.0

package/src/components/Tooltip.tsx

@@ -0,0 +1,78 @@
+import {
+  autoUpdate,
+  FloatingArrow,
+  FloatingPortal,
+  useDismiss,
+  useFloating,
+  useFocus,
+  useHover,
+  useInteractions,
+  useRole,
+  type Placement,
+} from '@floating-ui/react';
+import { useRef, useState, type ReactElement, type ReactNode } from 'react';
+import { floatingMiddleware, useTrigger } from '../floating';
+import { useConfig } from '../runtime';
+
+/** Props for {@link Tooltip}. */
+export interface TooltipProps {
+  /** Short text describing the trigger. Keep it plain; tooltips can't contain interactive content. */
+  content: ReactNode;
+  /** A single focusable element, e.g. an {@link IconButton}. */
+  children: ReactElement;
+  /**
+   * Preferred side. Flips when there isn't room.
+   * @default 'top'
+   */
+  placement?: Placement;
+  /**
+   * Delay before opening on hover, in ms. Opens immediately on keyboard focus.
+   * @default config.timing.tooltipDelay
+   */
+  delay?: number;
+}
+
+/**
+ * A short label shown on hover and keyboard focus.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip content="Search">
+ *   <IconButton aria-label="Search"><SearchIcon /></IconButton>
+ * </Tooltip>
+ * ```
+ */
+export function Tooltip({ content, children, placement = 'top', delay }: TooltipProps) {
+  const config = useConfig();
+  const [open, setOpen] = useState(false);
+  const arrowRef = useRef<SVGSVGElement>(null);
+  const { refs, floatingStyles, context } = useFloating({
+    open,
+    onOpenChange: setOpen,
+    placement,
+    transform: false,
+    whileElementsMounted: autoUpdate,
+    middleware: floatingMiddleware({ gap: 8, arrowRef }),
+  });
+  const { getReferenceProps, getFloatingProps } = useInteractions([
+    useHover(context, { move: false, delay: { open: delay ?? config.timing.tooltipDelay, close: 0 } }),
+    useFocus(context),
+    useDismiss(context),
+    useRole(context, { role: 'tooltip' }),
+  ]);
+  const trigger = useTrigger(children, refs.setReference, getReferenceProps);
+
+  return (
+    <>
+      {trigger}
+      {open && (
+        <FloatingPortal>
+          <div ref={refs.setFloating} style={floatingStyles} className="yarcl-floating yarcl-tooltip" {...getFloatingProps()}>
+            {content}
+            <FloatingArrow ref={arrowRef} context={context} className="yarcl-tooltip-arrow" width={10} height={5} />
+          </div>
+        </FloatingPortal>
+      )}
+    </>
+  );
+}

package/src/contrast.ts

@@ -0,0 +1,82 @@
+import { contrast, parseHex, readableOn } from './color.ts';
+import type { ColorPair, YarclShape } from './define.ts';
+
+/** A color combination in a config that falls below the required contrast. */
+export interface ContrastIssue {
+  /** The config path of the text color, e.g. `colors.warning` or `neutrals.muted`. */
+  path: string;
+  /** The color scheme the issue occurs in. */
+  scheme: 'light' | 'dark';
+  /** The contrast ratio, or `null` when it can't be computed (non-hex values). */
+  ratio: number | null;
+  /** A readable description of the problem. */
+  message: string;
+}
+
+const schemes = ['light', 'dark'] as const;
+
+function asPair(value: string | ColorPair): ColorPair {
+  return typeof value === 'string' ? { light: value, dark: value } : value;
+}
+
+/**
+ * Checks a config for text that doesn't reach a contrast ratio (WCAG AA, 4.5:1, by default)
+ * in light or dark mode. Returns the problems instead of printing them, so you can run it in a
+ * test, a CI step or a script.
+ *
+ * Checks the text drawn on each semantic color (its computed or configured `on`), and the
+ * neutral `text` and `muted` colors on the `bg` and `surface` backgrounds. Colors drawn as text
+ * need no check: their readable shade is computed automatically.
+ *
+ * @example
+ * ```ts
+ * import { checkContrast } from '@yarcl/react/contrast';
+ * import config from './src/yarcl.config';
+ *
+ * test('design system is readable', () => {
+ *   expect(checkContrast(config)).toEqual([]);
+ * });
+ * ```
+ */
+export function checkContrast(config: YarclShape, min = 4.5): ContrastIssue[] {
+  const issues: ContrastIssue[] = [];
+
+  for (const [key, token] of Object.entries(config.colors)) {
+    const on = token.on ? asPair(token.on) : null;
+    for (const scheme of schemes) {
+      const bg = parseHex(token[scheme]);
+      const path = `colors.${key}`;
+      if (!bg || (on && !parseHex(on[scheme]))) {
+        issues.push({ path, scheme, ratio: null, message: `${path}: can't check ${scheme} contrast of non-hex values; set \`on\` to a hex value` });
+        continue;
+      }
+      const fg = on ? parseHex(on[scheme])! : parseHex(readableOn(bg))!;
+      const ratio = contrast(bg, fg);
+      if (ratio < min) {
+        issues.push({ path, scheme, ratio, message: `${path}: ${scheme} text on this color is ${ratio.toFixed(2)}:1, below ${min}:1` });
+      }
+    }
+  }
+
+  const { neutrals } = config;
+  for (const text of ['text', 'muted'] as const) {
+    for (const ground of ['bg', 'surface'] as const) {
+      for (const scheme of schemes) {
+        const fg = parseHex(neutrals[text][scheme]);
+        const bg = parseHex(neutrals[ground][scheme]);
+        if (!fg || !bg) continue;
+        const ratio = contrast(fg, bg);
+        if (ratio < min) {
+          issues.push({
+            path: `neutrals.${text}`,
+            scheme,
+            ratio,
+            message: `neutrals.${text} on neutrals.${ground}: ${scheme} contrast is ${ratio.toFixed(2)}:1, below ${min}:1`,
+          });
+        }
+      }
+    }
+  }
+
+  return issues;
+}

package/src/css.ts

@@ -0,0 +1,228 @@
+import { contrast, mix, parseHex, readableOn, readableText, toHex } from './color.ts';
+import type { ColorPair, ColorToken, FontFaceToken, VariantToken, YarclShape } from './define.ts';
+
+const MIN_CONTRAST = 4.5;
+
+function ident(key: string): string {
+  return key.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`);
+}
+
+function pair({ light, dark }: ColorPair): string {
+  return light === dark ? light : `light-dark(${light}, ${dark})`;
+}
+
+function foreground(name: string, token: ColorToken, warn: (message: string) => void): string {
+  const modes = ['light', 'dark'] as const;
+  const on = typeof token.on === 'string' ? { light: token.on, dark: token.on } : token.on;
+
+  const resolved = modes.map((mode) => {
+    const bg = parseHex(token[mode]);
+    if (on) {
+      const fg = parseHex(on[mode]);
+      if (bg && fg && contrast(bg, fg) < MIN_CONTRAST) {
+        warn(`colors.${name}: ${mode} foreground contrast ${contrast(bg, fg).toFixed(2)}:1 is below ${MIN_CONTRAST}:1`);
+      }
+      return on[mode];
+    }
+    if (!bg) {
+      warn(`colors.${name}: cannot compute a ${mode} foreground from "${token[mode]}"; use a hex value or set \`on\``);
+      return '#ffffff';
+    }
+    const fg = readableOn(bg);
+    const ratio = contrast(bg, parseHex(fg)!);
+    if (ratio < MIN_CONTRAST) {
+      warn(`colors.${name}: best ${mode} foreground contrast is ${ratio.toFixed(2)}:1, below ${MIN_CONTRAST}:1`);
+    }
+    return fg;
+  });
+
+  return pair({ light: resolved[0], dark: resolved[1] });
+}
+
+const tint = (percent: number) => `color-mix(in oklab, var(--yarcl-c) ${percent}%, transparent)`;
+const shade = (percent: number) => `color-mix(in oklab, var(--yarcl-c), var(--yarcl-c-on) ${percent}%)`;
+
+const backgrounds: Record<VariantToken['background'], [string, string, string]> = {
+  fill: ['var(--yarcl-c)', shade(12), shade(20)],
+  tint: [tint(14), tint(22), tint(30)],
+  none: ['transparent', tint(10), tint(18)],
+};
+
+const borders: Record<VariantToken['border'], string> = {
+  color: 'var(--yarcl-c)',
+  neutral: 'var(--yarcl-neutral-border)',
+  none: 'transparent',
+};
+
+const texts: Record<VariantToken['text'], string> = {
+  on: 'var(--yarcl-c-on)',
+  color: 'var(--yarcl-c-text)',
+  neutral: 'var(--yarcl-neutral-text)',
+};
+
+const formats: Record<string, string> = { woff2: 'woff2', woff: 'woff', ttf: 'truetype', otf: 'opentype' };
+
+function fontFace(face: FontFaceToken): string {
+  const sources = (Array.isArray(face.src) ? face.src : [face.src]).map((src) => {
+    if (src.startsWith('local(')) return src;
+    const format = formats[src.split(/[?#]/)[0].split('.').pop()?.toLowerCase() ?? ''];
+    return `url(${JSON.stringify(src)})${format ? ` format("${format}")` : ''}`;
+  });
+  return rule('@font-face', [
+    ['font-family', JSON.stringify(face.family)],
+    ['src', sources.join(', ')],
+    ...(face.weight != null ? [['font-weight', face.weight] as [string, string | number]] : []),
+    ...(face.style ? [['font-style', face.style] as [string, string]] : []),
+    ['font-display', face.display ?? 'swap'],
+  ]);
+}
+
+const TEXT_TINTS = [0, 0.14, 0.22];
+
+function textShade(name: string, token: ColorToken, neutrals: YarclShape['neutrals']): string {
+  if (token.text) return pair(typeof token.text === 'string' ? { light: token.text, dark: token.text } : token.text);
+  const modes = ['light', 'dark'] as const;
+  const resolved = modes.map((mode) => {
+    const color = parseHex(token[mode]);
+    const text = parseHex(neutrals.text[mode]);
+    const grounds = [parseHex(neutrals.bg[mode]), parseHex(neutrals.surface[mode])];
+    if (!color || !text || grounds.some((g) => !g)) return token[mode];
+    const backgrounds = grounds.flatMap((ground) => TEXT_TINTS.map((alpha) => mix(ground!, color, alpha)));
+    return toHex(readableText(color, backgrounds, text, MIN_CONTRAST));
+  });
+  return pair({ light: resolved[0], dark: resolved[1] });
+}
+
+function rule(selector: string, declarations: [string, string | number][]): string {
+  return `${selector} {\n${declarations.map(([p, v]) => `  ${p}: ${v};`).join('\n')}\n}`;
+}
+
+/**
+ * Generates the stylesheet for a config: CSS variables on `:root`, one class per key and
+ * `@font-face` rules. The Vite plugin calls this at build time; call it yourself to preview
+ * or switch themes at runtime (inject the result into a `<style>` element).
+ *
+ * @param config A config from `defineConfig`, e.g. one of `@yarcl/react/themes`.
+ * @param warn Receives contrast warnings.
+ */
+export function generateCss(config: YarclShape, warn: (message: string) => void = () => {}): string {
+  const root: [string, string | number][] = [['color-scheme', 'light dark']];
+  const rules: string[] = [];
+
+  for (const [key, token] of Object.entries(config.colors)) {
+    const k = ident(key);
+    root.push(
+      [`--yarcl-color-${k}`, pair(token)],
+      [`--yarcl-color-${k}-on`, foreground(key, token, warn)],
+      [`--yarcl-color-${k}-text`, textShade(key, token, config.neutrals)],
+    );
+    rules.push(
+      rule(`.yarcl-color-${k}`, [
+        ['--yarcl-c', `var(--yarcl-color-${k})`],
+        ['--yarcl-c-on', `var(--yarcl-color-${k}-on)`],
+        ['--yarcl-c-text', `var(--yarcl-color-${k}-text)`],
+      ]),
+    );
+  }
+
+  for (const [key, value] of Object.entries(config.neutrals)) root.push([`--yarcl-neutral-${ident(key)}`, pair(value)]);
+
+  for (const [key, size] of Object.entries(config.sizes)) {
+    const k = ident(key);
+    root.push(
+      [`--yarcl-size-${k}-height`, size.height],
+      [`--yarcl-size-${k}-padding-x`, size.paddingX],
+      [`--yarcl-size-${k}-font-size`, size.fontSize],
+      [`--yarcl-size-${k}-icon-size`, size.iconSize],
+    );
+    rules.push(
+      rule(`.yarcl-size-${k}`, [
+        ['--yarcl-h', `var(--yarcl-size-${k}-height)`],
+        ['--yarcl-px', `var(--yarcl-size-${k}-padding-x)`],
+        ['--yarcl-fs', `var(--yarcl-size-${k}-font-size)`],
+        ['--yarcl-icon', `var(--yarcl-size-${k}-icon-size)`],
+      ]),
+    );
+  }
+
+  for (const [key, value] of Object.entries(config.radii)) {
+    const k = ident(key);
+    root.push([`--yarcl-radius-${k}`, value]);
+    rules.push(rule(`.yarcl-radius-${k}`, [['--yarcl-r', `var(--yarcl-radius-${k})`]]));
+  }
+
+  for (const [key, variant] of Object.entries(config.variants)) {
+    const [bg, hover, active] = backgrounds[variant.background];
+    rules.push(
+      rule(`.yarcl-variant-${ident(key)}`, [
+        ['--yarcl-v-bg', bg],
+        ['--yarcl-v-bg-hover', hover],
+        ['--yarcl-v-bg-active', active],
+        ['--yarcl-v-border', borders[variant.border]],
+        ['--yarcl-v-fg', texts[variant.text]],
+      ]),
+    );
+  }
+
+  for (const [key, value] of Object.entries(config.spacing)) {
+    const k = ident(key);
+    root.push([`--yarcl-space-${k}`, value]);
+    rules.push(
+      rule(`.yarcl-gap-${k}`, [['gap', `var(--yarcl-space-${k})`]]),
+      rule(`.yarcl-padding-${k}`, [['padding', `var(--yarcl-space-${k})`]]),
+    );
+  }
+
+  for (const [key, value] of Object.entries(config.shadows)) {
+    const k = ident(key);
+    root.push([`--yarcl-shadow-${k}`, value]);
+    rules.push(rule(`.yarcl-shadow-${k}`, [['box-shadow', `var(--yarcl-shadow-${k})`]]));
+  }
+  for (const [key, value] of Object.entries(config.modalSizes)) {
+    const k = ident(key);
+    root.push([`--yarcl-modal-${k}`, value]);
+    rules.push(rule(`.yarcl-modal-size-${k}`, [['--yarcl-modal-width', `var(--yarcl-modal-${k})`]]));
+  }
+
+  for (const [key, density] of Object.entries(config.density)) {
+    rules.push(
+      rule(`.yarcl-density-${ident(key)}`, [
+        ['--yarcl-cell-px', density.paddingX],
+        ['--yarcl-cell-py', density.paddingY],
+        ['--yarcl-cell-fs', density.fontSize],
+      ]),
+    );
+  }
+
+  for (const [key, value] of Object.entries(config.typography.families)) root.push([`--yarcl-font-${ident(key)}`, value]);
+
+  for (const [key, style] of Object.entries(config.typography.styles)) {
+    rules.push(
+      rule(`.yarcl-type-${ident(key)}`, [
+        ['font-family', `var(--yarcl-font-${ident(style.family)})`],
+        ['font-size', style.size],
+        ['font-weight', style.weight],
+        ['line-height', style.lineHeight],
+        ...(style.letterSpacing ? [['letter-spacing', style.letterSpacing] as [string, string]] : []),
+      ]),
+    );
+  }
+
+  for (const [key, value] of Object.entries(config.zIndex)) root.push([`--yarcl-z-${ident(key)}`, value]);
+  for (const [key, value] of Object.entries(config.motion)) root.push([`--yarcl-motion-${ident(key)}`, value]);
+  for (const [key, value] of Object.entries(config.borders)) root.push([`--yarcl-border-${ident(key)}`, value]);
+
+  root.push(
+    ['--yarcl-focus-width', config.focusRing.width],
+    ['--yarcl-focus-offset', config.focusRing.offset],
+    ['--yarcl-focus-style', config.focusRing.style ?? 'solid'],
+    ['--yarcl-focus-color', `var(--yarcl-color-${ident(config.focusRing.color)})`],
+    ['--yarcl-error', `var(--yarcl-color-${ident(config.defaults.errorColor)})`],
+    ['--yarcl-floating-shadow', `var(--yarcl-shadow-${ident(config.defaults.floatingShadow)})`],
+    ['--yarcl-padding', `var(--yarcl-space-${ident(config.defaults.padding)})`],
+    ['--yarcl-gap', `var(--yarcl-space-${ident(config.defaults.gap)})`],
+  );
+
+  const faces = (config.typography.fontFaces ?? []).map(fontFace);
+  return [...faces, rule(':root', root), ...rules].join('\n\n') + '\n';
+}

package/src/define.check.ts

@@ -0,0 +1,259 @@
+import { defineConfig } from './define';
+import defaults from './yarcl.config';
+
+defineConfig({ ...defaults, colors: { ...defaults.colors, brand: { light: '#000', dark: '#fff' } } });
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  colors: { primary: { light: '#2d4bb8' } },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  defaults: { ...defaults.defaults, size: 'xxl' },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  focusRing: { ...defaults.focusRing, color: 'nope' },
+});
+
+defineConfig({
+  ...defaults,
+  typography: {
+    ...defaults.typography,
+    // @ts-expect-error
+    styles: { body: { family: 'serif', size: '1rem', weight: 400, lineHeight: 1.5 } },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  radii: { ...defaults.radii, 'extra round': '2rem' },
+});
+
+defineConfig({
+  ...defaults,
+  zIndex: { ...defaults.zIndex, banner: 900 },
+  neutrals: { ...defaults.neutrals, raised: { light: '#fff', dark: '#222' } },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  zIndex: { dropdown: 1000, tooltip: 1100, dialog: 1200 },
+});
+
+defineConfig({
+  ...defaults,
+  variants: { ...defaults.variants, link: { background: 'none', border: 'none', text: 'color' } },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  variants: { solid: { background: 'gradient', border: 'color', text: 'on' } },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  defaults: { ...defaults.defaults, errorColor: 'red' },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  defaults: { ...defaults.defaults, textStyle: 'huge' },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  defaults: { ...defaults.defaults, gap: 'tight' },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  defaults: { ...defaults.defaults, softVariant: 'subtle' },
+});
+
+defineConfig({
+  ...defaults,
+  typography: {
+    ...defaults.typography,
+    fontFaces: [{ family: 'Inter', src: ['/fonts/inter.woff2', 'local(Inter)'], weight: '100 900' }],
+  },
+});
+
+defineConfig({
+  ...defaults,
+  typography: {
+    ...defaults.typography,
+    // @ts-expect-error
+    headings: { ...defaults.typography.headings, h3: 'huge' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  typography: {
+    ...defaults.typography,
+    // @ts-expect-error
+    headings: { h1: 'display', h2: 'heading' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  defaults: { ...defaults.defaults, labelStyle: 'tiny' },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    Button: { radius: 'square', variant: 'outline' },
+    IconButton: { radius: 'size' },
+    Card: { padding: 'xl', shadow: 'lg' },
+    Stack: { gap: 'sm' },
+    Pagination: { size: 'sm', variant: 'outline', selectedVariant: 'solid' },
+    Breadcrumb: { textStyle: 'caption', color: 'neutral' },
+    Accordion: { size: 'sm', radius: 'size', color: 'success' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Pagination: { selectedVariant: 'filled' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Breadcrumb: { size: 'sm' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Breadcrumb: { textStyle: 'huge' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Accordion: { variant: 'solid' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Buton: { radius: 'square' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Card: { variant: 'solid' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Button: { radius: 'pill' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  radii: { ...defaults.radii, size: '1rem' },
+});
+
+defineConfig({ ...defaults, components: { CommandPalette: { size: 'lg', radius: 'size', color: 'danger' } } });
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    CommandPalette: { variant: 'solid' },
+  },
+});
+
+defineConfig({ ...defaults, defaults: { ...defaults.defaults, radius: 'square' } });
+
+defineConfig({
+  ...defaults,
+  modalSizes: { ...defaults.modalSizes, huge: '80rem' },
+  components: { Dialog: { size: 'huge' }, Drawer: { size: 'sm' } },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Dialog: { size: 'giant' },
+  },
+});
+
+defineConfig({ ...defaults, components: { Label: { textStyle: 'caption', color: 'neutral' } } });
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Label: { textStyle: 'tiny' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Label: { size: 'sm' },
+  },
+});
+
+defineConfig({
+  ...defaults,
+  // @ts-expect-error
+  defaults: { ...defaults.defaults, modalSize: 'giant' },
+});
+
+defineConfig({
+  ...defaults,
+  colors: { ...defaults.colors, primary: { light: '#2d4bb8', dark: '#8aa2ff', text: { light: '#1e3480', dark: '#c3cfff' } } },
+});
+
+defineConfig({
+  ...defaults,
+  components: { Progress: { size: 'lg', color: 'success', radius: 'rounded' } },
+});
+
+defineConfig({
+  ...defaults,
+  components: {
+    // @ts-expect-error
+    Progress: { variant: 'solid' },
+  },
+});