@spatika/react 1.3.1 → 1.5.0

package/src/lib/create-theme.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  createTheme,
+  injectCustomThemeStyles,
+  PALETTE_CSS_VARS,
+  themeToCss,
+} from "./create-theme";
+
+describe("createTheme", () => {
+  afterEach(() => {
+    document.getElementById("spk-custom-themes")?.remove();
+  });
+
+  it("overlays palette, glass, and shape onto a built-in theme", () => {
+    const theme = createTheme({
+      id: "brand",
+      label: "Brand",
+      extends: "neelam",
+      palette: { primary: "#22c55e", primaryForeground: "#052e16", chart1: "#4ade80" },
+      glass: { blur: "12px" },
+      shape: { radius: "0.75rem" },
+      typography: { fontFamily: '"Source Sans 3", sans-serif' },
+      vars: { "--shadow-soft": "none" },
+    });
+
+    expect(theme.id).toBe("brand");
+    expect(theme.label).toBe("Brand");
+    expect(theme.extends).toBe("neelam");
+    expect(theme.colorScheme).toBe("dark");
+    expect(theme.vars["--primary"]).toBe("#22c55e");
+    expect(theme.vars["--primary-foreground"]).toBe("#052e16");
+    expect(theme.vars["--chart-1"]).toBe("#4ade80");
+    expect(theme.vars["--glass-blur"]).toBe("12px");
+    expect(theme.vars["--radius"]).toBe("0.75rem");
+    expect(theme.vars["--font-sans"]).toBe('"Source Sans 3", sans-serif');
+    expect(theme.vars["--shadow-soft"]).toBe("none");
+  });
+
+  it("defaults to a light Mukta base", () => {
+    const theme = createTheme({ id: "lilac", palette: { primary: "#7c3aed" } });
+    expect(theme.extends).toBe("mukta");
+    expect(theme.colorScheme).toBe("light");
+    expect(theme.label).toBe("lilac");
+  });
+
+  it("rejects empty and built-in ids", () => {
+    expect(() => createTheme({ id: "   " })).toThrow(/required/);
+    expect(() => createTheme({ id: "neelam" })).toThrow(/built-in/);
+  });
+
+  it("serializes an attribute selector stylesheet", () => {
+    const theme = createTheme({
+      id: "brand",
+      palette: { primary: "#7c3aed" },
+      typography: { fontFamily: "Georgia, serif" },
+    });
+    const css = themeToCss(theme);
+    expect(css).toContain('[data-spk-theme="brand"]');
+    expect(css).toContain("--primary: #7c3aed;");
+    expect(css).toContain("font-family: var(--font-sans);");
+  });
+
+  it("injects and replaces a document stylesheet", () => {
+    const brand = createTheme({ id: "brand", palette: { primary: "#7c3aed" } });
+    injectCustomThemeStyles([brand]);
+    const el = document.getElementById("spk-custom-themes");
+    expect(el?.tagName).toBe("STYLE");
+    expect(el?.textContent).toContain("--primary: #7c3aed;");
+
+    injectCustomThemeStyles([]);
+    expect(document.getElementById("spk-custom-themes")).toBeNull();
+  });
+
+  it("maps every palette key to a CSS variable", () => {
+    expect(PALETTE_CSS_VARS.primary).toBe("--primary");
+    expect(PALETTE_CSS_VARS.mutedForeground).toBe("--muted-foreground");
+    expect(Object.keys(PALETTE_CSS_VARS).length).toBeGreaterThan(20);
+  });
+});

package/src/lib/create-theme.ts

@@ -0,0 +1,249 @@
+import { isDarkTheme, isThemeId, type BuiltinThemeId, type ThemeId } from "./themes";
+
+/** Color tokens that map 1:1 onto Spatika CSS variables. */
+export type ThemePalette = {
+  background?: string;
+  foreground?: string;
+  card?: string;
+  cardForeground?: string;
+  popover?: string;
+  popoverForeground?: string;
+  primary?: string;
+  primaryForeground?: string;
+  secondary?: string;
+  secondaryForeground?: string;
+  muted?: string;
+  mutedForeground?: string;
+  accent?: string;
+  accentForeground?: string;
+  destructive?: string;
+  destructiveForeground?: string;
+  border?: string;
+  input?: string;
+  inputBackground?: string;
+  switchBackground?: string;
+  ring?: string;
+  sidebar?: string;
+  sidebarForeground?: string;
+  sidebarPrimary?: string;
+  sidebarPrimaryForeground?: string;
+  sidebarAccent?: string;
+  sidebarAccentForeground?: string;
+  sidebarBorder?: string;
+  sidebarRing?: string;
+  accentInfo?: string;
+  accentInfoBg?: string;
+  accentHighlight?: string;
+  accentHighlightBg?: string;
+  accentWarm?: string;
+  accentWarmBg?: string;
+  accentDangerBg?: string;
+  chart1?: string;
+  chart2?: string;
+  chart3?: string;
+  chart4?: string;
+  chart5?: string;
+};
+
+export type ThemeGlass = {
+  bg?: string;
+  panelBg?: string;
+  mutedBg?: string;
+  headerBg?: string;
+  border?: string;
+  blur?: string;
+  headerBlur?: string;
+  menuBlur?: string;
+  saturate?: string;
+  shadow?: string;
+  highlight?: string;
+  overlayBg?: string;
+  overlayBlur?: string;
+};
+
+export type ThemeShape = {
+  radius?: string;
+  radiusCard?: string;
+  radiusControl?: string;
+  radiusPill?: string;
+};
+
+export type ThemeTypography = {
+  fontFamily?: string;
+};
+
+export type CreateThemeOptions = {
+  /** Unique id written to `data-spk-theme`. Must not collide with a built-in id. */
+  id: string;
+  label?: string;
+  /** Built-in theme whose CSS variables are inherited, then overlaid. */
+  extends?: BuiltinThemeId;
+  colorScheme?: "light" | "dark";
+  palette?: ThemePalette;
+  glass?: ThemeGlass;
+  shape?: ThemeShape;
+  typography?: ThemeTypography;
+  /** Escape hatch: raw CSS custom properties, e.g. `{ "--shadow-soft": "none" }`. */
+  vars?: Record<string, string>;
+};
+
+export type SpatikaTheme = {
+  id: string;
+  label: string;
+  extends: BuiltinThemeId;
+  colorScheme: "light" | "dark";
+  vars: Record<string, string>;
+};
+
+export const PALETTE_CSS_VARS = {
+  background: "--background",
+  foreground: "--foreground",
+  card: "--card",
+  cardForeground: "--card-foreground",
+  popover: "--popover",
+  popoverForeground: "--popover-foreground",
+  primary: "--primary",
+  primaryForeground: "--primary-foreground",
+  secondary: "--secondary",
+  secondaryForeground: "--secondary-foreground",
+  muted: "--muted",
+  mutedForeground: "--muted-foreground",
+  accent: "--accent",
+  accentForeground: "--accent-foreground",
+  destructive: "--destructive",
+  destructiveForeground: "--destructive-foreground",
+  border: "--border",
+  input: "--input",
+  inputBackground: "--input-background",
+  switchBackground: "--switch-background",
+  ring: "--ring",
+  sidebar: "--sidebar",
+  sidebarForeground: "--sidebar-foreground",
+  sidebarPrimary: "--sidebar-primary",
+  sidebarPrimaryForeground: "--sidebar-primary-foreground",
+  sidebarAccent: "--sidebar-accent",
+  sidebarAccentForeground: "--sidebar-accent-foreground",
+  sidebarBorder: "--sidebar-border",
+  sidebarRing: "--sidebar-ring",
+  accentInfo: "--accent-info",
+  accentInfoBg: "--accent-info-bg",
+  accentHighlight: "--accent-highlight",
+  accentHighlightBg: "--accent-highlight-bg",
+  accentWarm: "--accent-warm",
+  accentWarmBg: "--accent-warm-bg",
+  accentDangerBg: "--accent-danger-bg",
+  chart1: "--chart-1",
+  chart2: "--chart-2",
+  chart3: "--chart-3",
+  chart4: "--chart-4",
+  chart5: "--chart-5",
+} as const satisfies Record<keyof ThemePalette, string>;
+
+export const GLASS_CSS_VARS = {
+  bg: "--glass-bg",
+  panelBg: "--glass-panel-bg",
+  mutedBg: "--glass-muted-bg",
+  headerBg: "--glass-header-bg",
+  border: "--glass-border",
+  blur: "--glass-blur",
+  headerBlur: "--glass-header-blur",
+  menuBlur: "--glass-menu-blur",
+  saturate: "--glass-saturate",
+  shadow: "--glass-shadow",
+  highlight: "--glass-highlight",
+  overlayBg: "--modal-overlay-bg",
+  overlayBlur: "--modal-overlay-blur",
+} as const satisfies Record<keyof ThemeGlass, string>;
+
+export const SHAPE_CSS_VARS = {
+  radius: "--radius",
+  radiusCard: "--radius-card",
+  radiusControl: "--radius-control",
+  radiusPill: "--radius-pill",
+} as const satisfies Record<keyof ThemeShape, string>;
+
+const CUSTOM_THEME_STYLE_ID = "spk-custom-themes";
+
+function assignMappedVars<T extends Record<string, string>>(
+  vars: Record<string, string>,
+  source: object | undefined,
+  map: T,
+) {
+  if (!source) return;
+  for (const [key, cssVar] of Object.entries(map)) {
+    const value = (source as Record<string, string | undefined>)[key];
+    if (typeof value === "string" && value.length > 0) vars[cssVar] = value;
+  }
+}
+
+/** Build a custom theme that overlays CSS variables on a built-in Spatika theme. */
+export function createTheme(options: CreateThemeOptions): SpatikaTheme {
+  const id = options.id.trim();
+  if (!id) {
+    throw new Error("createTheme: `id` is required.");
+  }
+  if (isThemeId(id)) {
+    throw new Error(`createTheme: "${id}" is a built-in theme. Choose a different id.`);
+  }
+
+  const base: BuiltinThemeId = options.extends ?? "mukta";
+  const colorScheme = options.colorScheme ?? (isDarkTheme(base) ? "dark" : "light");
+  const vars: Record<string, string> = {};
+
+  assignMappedVars(vars, options.palette, PALETTE_CSS_VARS);
+  assignMappedVars(vars, options.glass, GLASS_CSS_VARS);
+  assignMappedVars(vars, options.shape, SHAPE_CSS_VARS);
+
+  if (options.typography?.fontFamily) {
+    vars["--font-sans"] = options.typography.fontFamily;
+  }
+  if (options.vars) {
+    for (const [key, value] of Object.entries(options.vars)) {
+      if (value) vars[key] = value;
+    }
+  }
+
+  return {
+    id,
+    label: options.label?.trim() || id,
+    extends: base,
+    colorScheme,
+    vars,
+  };
+}
+
+/** Serialize a custom theme as an attribute selector rule. */
+export function themeToCss(theme: SpatikaTheme): string {
+  const entries = Object.entries(theme.vars);
+  if (!entries.length) {
+    return `[data-spk-theme="${theme.id}"] {\n}\n`;
+  }
+  const decls = entries.map(([key, value]) => `  ${key}: ${value};`).join("\n");
+  const font = theme.vars["--font-sans"]
+    ? `\n  font-family: var(--font-sans);`
+    : "";
+  return `[data-spk-theme="${theme.id}"] {\n${decls}${font}\n}\n`;
+}
+
+/** Inject (or replace) a single stylesheet for every registered custom theme. */
+export function injectCustomThemeStyles(themes: readonly SpatikaTheme[]): void {
+  if (typeof document === "undefined") return;
+  let el = document.getElementById(CUSTOM_THEME_STYLE_ID) as HTMLStyleElement | null;
+  if (!themes.length) {
+    el?.remove();
+    return;
+  }
+  if (!el) {
+    el = document.createElement("style");
+    el.id = CUSTOM_THEME_STYLE_ID;
+    document.head.appendChild(el);
+  }
+  el.textContent = themes.map(themeToCss).join("\n");
+}
+
+export function findCustomTheme(
+  theme: ThemeId,
+  customThemes: readonly SpatikaTheme[] | undefined,
+): SpatikaTheme | undefined {
+  return customThemes?.find((item) => item.id === theme);
+}

package/src/lib/scheduler.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it } from "vitest";
 import {
   addDays,
+  calendarVisibleRange,
+  CALENDAR_AGENDA_DAYS,
+  eventColorStyle,
   formatDateRange,
   getMonthGrid,
   getTimelineRange,
@@ -35,6 +38,20 @@ describe("scheduler dates", () => {
     expect(grid[0].getMonth()).toBe(6);
   });
 
+  it("reports the exclusive visible range for month, week, and agenda", () => {
+    const month = calendarVisibleRange("month", new Date(2026, 7, 15), 0);
+    expect(month.start.getDate()).toBe(26);
+    expect(month.start.getMonth()).toBe(6);
+    expect(month.end.getTime()).toBe(addDays(getMonthGrid(new Date(2026, 7, 15), 0)[41], 1).getTime());
+
+    const week = calendarVisibleRange("week", new Date(2026, 7, 15), 0);
+    expect(week.start.getDay()).toBe(0);
+    expect(week.end.getTime() - week.start.getTime()).toBe(7 * 86_400_000);
+
+    const agenda = calendarVisibleRange("agenda", new Date(2026, 7, 3), 0);
+    expect(agenda.end.getTime() - agenda.start.getTime()).toBe(CALENDAR_AGENDA_DAYS * 86_400_000);
+  });
+
   it("returns Sunday-first weekday labels by default", () => {
     const labels = weekdayLabels(0, "en-US");
     expect(labels[0]).toMatch(/^Sun/);
@@ -197,3 +214,12 @@ describe("scheduler formatting", () => {
     expect(lastInstant(event).getDate()).toBe(3);
   });
 });
+
+describe("eventColorStyle", () => {
+  it("uses solid bar fills with light labels for month-spanning events", () => {
+    expect(eventColorStyle("rose", "bar")).toEqual({
+      backgroundColor: "var(--destructive)",
+      color: "#ffffff",
+    });
+  });
+});

package/src/lib/scheduler.ts

@@ -187,6 +187,40 @@ export function getWeekDays(date: Date, weekStartsOn = 0): Date[] {
   return Array.from({ length: 7 }, (_, i) => addDays(start, i));
 }
 
+/** Inclusive first instant of the agenda window. */
+export const CALENDAR_AGENDA_DAYS = 14;
+
+export type CalendarVisibleRange = {
+  start: Date;
+  /** Exclusive end (start of the day after the last visible day). */
+  end: Date;
+};
+
+/**
+ * Days the calendar actually paints for a view.
+ * Month includes leading/trailing grid days, not just the named month.
+ */
+export function calendarVisibleRange(
+  view: CalendarView,
+  date: Date,
+  weekStartsOn = 0,
+): CalendarVisibleRange {
+  if (view === "month") {
+    const grid = getMonthGrid(date, weekStartsOn);
+    return { start: grid[0], end: addDays(grid[grid.length - 1], 1) };
+  }
+  if (view === "week") {
+    const days = getWeekDays(date, weekStartsOn);
+    return { start: days[0], end: addDays(days[6], 1) };
+  }
+  if (view === "agenda") {
+    const days = agendaDays(date, CALENDAR_AGENDA_DAYS);
+    return { start: days[0], end: addDays(days[days.length - 1], 1) };
+  }
+  const start = startOfDay(date);
+  return { start, end: addDays(start, 1) };
+}
+
 export function weekdayLabels(weekStartsOn = 0, locale?: string): string[] {
   const sunday = new Date(2026, 7, 2);
   return Array.from({ length: 7 }, (_, i) => {
@@ -669,8 +703,8 @@ export function eventColorStyle(
   if (variant === "dot") return { backgroundColor: color };
   if (variant === "bar") {
     return {
-      backgroundColor: `color-mix(in srgb, ${color} 88%, transparent)`,
-      color: "var(--primary-foreground)",
+      backgroundColor: color,
+      color: "#ffffff",
     };
   }
   if (variant === "wash") {

package/src/lib/themes.test.ts

@@ -63,6 +63,17 @@ describe("themes", () => {
     expect(document.documentElement.classList.contains("sandhya")).toBe(true);
   });
 
+  it("applies a custom theme id on top of its base", () => {
+    applyTheme("brand", undefined, {
+      id: "brand",
+      extends: "neelam",
+      colorScheme: "dark",
+    });
+    expect(document.documentElement.classList.contains("neelam")).toBe(true);
+    expect(document.documentElement.getAttribute("data-spk-theme")).toBe("brand");
+    expect(document.documentElement.style.colorScheme).toBe("dark");
+  });
+
   it("reads and writes stored themes", () => {
     expect(readStoredTheme(SPATIKA_THEME_STORAGE_KEY)).toBeNull();
     writeStoredTheme(SPATIKA_THEME_STORAGE_KEY, "sandhya");
@@ -70,4 +81,10 @@ describe("themes", () => {
     writeStoredTheme(false, "neelam");
     expect(readStoredTheme(SPATIKA_THEME_STORAGE_KEY)).toBe("sandhya");
   });
+
+  it("restores a custom stored theme when it is allowed", () => {
+    writeStoredTheme(SPATIKA_THEME_STORAGE_KEY, "brand");
+    expect(readStoredTheme(SPATIKA_THEME_STORAGE_KEY)).toBeNull();
+    expect(readStoredTheme(SPATIKA_THEME_STORAGE_KEY, ["brand"])).toBe("brand");
+  });
 });

package/src/lib/themes.ts

@@ -1,14 +1,20 @@
-/** Supported theme identifiers applied as classes on a root element. */
+/** Supported built-in theme identifiers applied as classes on a root element. */
 export const THEME_IDS = ["mukta", "neelam", "usha", "sandhya"] as const;
 
-export type ThemeId = (typeof THEME_IDS)[number];
+export type BuiltinThemeId = (typeof THEME_IDS)[number];
 
-export const DEFAULT_THEME: ThemeId = "mukta";
+/**
+ * Built-in ids plus custom ids from `createTheme`.
+ * Custom strings keep autocomplete for Mukta / Neelam / Usha / Sandhya.
+ */
+export type ThemeId = BuiltinThemeId | (string & {});
+
+export const DEFAULT_THEME: BuiltinThemeId = "mukta";
 
 /** Default `localStorage` key used by the docs site and `SpatikaThemeProvider`. */
 export const SPATIKA_THEME_STORAGE_KEY = "spk-theme";
 
-export const THEME_LABELS: Record<ThemeId, string> = {
+export const THEME_LABELS: Record<BuiltinThemeId, string> = {
   mukta: "Mukta",
   neelam: "Neelam",
   usha: "Usha",
@@ -17,7 +23,7 @@ export const THEME_LABELS: Record<ThemeId, string> = {
 
 const THEME_CLASS_LIST = ["neelam", "usha", "sandhya"] as const;
 
-export function isThemeId(value: unknown): value is ThemeId {
+export function isThemeId(value: unknown): value is BuiltinThemeId {
   return typeof value === "string" && (THEME_IDS as readonly string[]).includes(value);
 }
 
@@ -25,12 +31,24 @@ export function isDarkTheme(theme: ThemeId): boolean {
   return theme === "neelam" || theme === "sandhya";
 }
 
+export type ApplyThemeCustom = {
+  id: string;
+  extends: BuiltinThemeId;
+  colorScheme: "light" | "dark";
+};
+
 /** Read a persisted theme. Returns `null` when missing or invalid. */
-export function readStoredTheme(storageKey?: string | false): ThemeId | null {
+export function readStoredTheme(
+  storageKey?: string | false,
+  allowed?: readonly string[],
+): ThemeId | null {
   if (!storageKey || typeof window === "undefined") return null;
   try {
     const value = window.localStorage.getItem(storageKey);
-    return isThemeId(value) ? value : null;
+    if (!value) return null;
+    if (isThemeId(value)) return value;
+    if (allowed?.includes(value)) return value;
+    return null;
   } catch {
     return null;
   }
@@ -46,14 +64,27 @@ export function writeStoredTheme(storageKey: string | false | undefined, theme:
   }
 }
 
+function resolveBase(theme: ThemeId, custom?: ApplyThemeCustom | null): BuiltinThemeId {
+  if (custom) return custom.extends;
+  return isThemeId(theme) ? theme : DEFAULT_THEME;
+}
+
 /** Apply a theme class to an element (defaults to `<html>`). */
-export function applyTheme(theme: ThemeId, target?: HTMLElement | null) {
+export function applyTheme(
+  theme: ThemeId,
+  target?: HTMLElement | null,
+  custom?: ApplyThemeCustom | null,
+) {
   if (typeof document === "undefined") return;
   const root = target ?? document.documentElement;
+  const base = resolveBase(theme, custom);
+  const id = custom?.id ?? theme;
+
   root.classList.remove(...THEME_CLASS_LIST);
-  if (theme !== DEFAULT_THEME) {
-    root.classList.add(theme);
+  if (base !== DEFAULT_THEME) {
+    root.classList.add(base);
   }
-  root.setAttribute("data-spk-theme", theme);
-  root.style.colorScheme = isDarkTheme(theme) ? "dark" : "light";
+  root.setAttribute("data-spk-theme", id);
+  const dark = custom ? custom.colorScheme === "dark" : isDarkTheme(base);
+  root.style.colorScheme = dark ? "dark" : "light";
 }

package/src/lib/use-media-query.test.tsx

@@ -0,0 +1,80 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  breakpointDown,
+  breakpointUp,
+  useBreakpoint,
+  useBreakpointDown,
+  useBreakpointUp,
+  useIsMobile,
+  useMediaQuery,
+} from "./use-media-query";
+
+function Probe({ query }: { query: string }) {
+  const matches = useMediaQuery(query);
+  return <span data-testid="mq">{String(matches)}</span>;
+}
+
+function BreakpointProbe() {
+  const current = useBreakpoint();
+  const mdUp = useBreakpointUp("md");
+  const mdDown = useBreakpointDown("md");
+  const mobile = useIsMobile();
+  return (
+    <div>
+      <span data-testid="bp">{current}</span>
+      <span data-testid="up">{String(mdUp)}</span>
+      <span data-testid="down">{String(mdDown)}</span>
+      <span data-testid="mobile">{String(mobile)}</span>
+    </div>
+  );
+}
+
+function mockMatchMedia(matching: (query: string) => boolean) {
+  Object.defineProperty(window, "matchMedia", {
+    writable: true,
+    value: (query: string) => ({
+      matches: matching(query),
+      media: query,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+    }),
+  });
+}
+
+describe("useMediaQuery", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("is false until mounted, then follows matchMedia", () => {
+    mockMatchMedia((query) => query.includes("900"));
+    render(<Probe query="(min-width: 900px)" />);
+    expect(screen.getByTestId("mq")).toHaveTextContent("true");
+  });
+
+  it("reports the current breakpoint and aliases", () => {
+    mockMatchMedia((query) => {
+      if (query === breakpointUp("sm")) return true;
+      if (query === breakpointUp("md")) return true;
+      if (query === breakpointUp("lg")) return false;
+      if (query === breakpointUp("xl")) return false;
+      if (query === breakpointDown("md")) return false;
+      return false;
+    });
+    render(<BreakpointProbe />);
+    expect(screen.getByTestId("bp")).toHaveTextContent("md");
+    expect(screen.getByTestId("up")).toHaveTextContent("true");
+    expect(screen.getByTestId("down")).toHaveTextContent("false");
+    expect(screen.getByTestId("mobile")).toHaveTextContent("false");
+  });
+
+  it("treats viewports below md as mobile", () => {
+    mockMatchMedia((query) => query === breakpointDown("md"));
+    render(<BreakpointProbe />);
+    expect(screen.getByTestId("bp")).toHaveTextContent("xs");
+    expect(screen.getByTestId("mobile")).toHaveTextContent("true");
+  });
+});

package/src/lib/use-media-query.ts

@@ -1,4 +1,11 @@
 import { useEffect, useState } from "react";
+import {
+  BREAKPOINT_KEYS,
+  BREAKPOINTS,
+  breakpointDown,
+  breakpointUp,
+  type Breakpoint,
+} from "./breakpoints";
 
 /** Subscribe to a CSS media query. Defaults to `false` until mounted. */
 export function useMediaQuery(query: string): boolean {
@@ -18,5 +25,32 @@ export function useMediaQuery(query: string): boolean {
 
 /** True when the viewport is below the `md` breakpoint (768px). */
 export function useIsMobile(): boolean {
-  return useMediaQuery("(max-width: 767px)");
+  return useMediaQuery(breakpointDown("md"));
 }
+
+/** True from this breakpoint up (`xs` is always true). */
+export function useBreakpointUp(key: Breakpoint): boolean {
+  const matches = useMediaQuery(breakpointUp(key));
+  return key === "xs" || matches;
+}
+
+/** True strictly below this breakpoint. */
+export function useBreakpointDown(key: Exclude<Breakpoint, "xs">): boolean {
+  return useMediaQuery(breakpointDown(key));
+}
+
+/** Largest matching breakpoint, starting at `xs`. */
+export function useBreakpoint(): Breakpoint {
+  const sm = useMediaQuery(breakpointUp("sm"));
+  const md = useMediaQuery(breakpointUp("md"));
+  const lg = useMediaQuery(breakpointUp("lg"));
+  const xl = useMediaQuery(breakpointUp("xl"));
+  if (xl) return "xl";
+  if (lg) return "lg";
+  if (md) return "md";
+  if (sm) return "sm";
+  return "xs";
+}
+
+export { BREAKPOINTS, BREAKPOINT_KEYS, breakpointDown, breakpointUp };
+export type { Breakpoint };