@softure-ai/theme-kit 0.0.0-stage → 0.1.0

package/src/build/theme-stylesheet.ts

@@ -0,0 +1,43 @@
+import { copyFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { buildThemeCss } from "../build-theme-css.js";
+import type { ThemeDefinition } from "../theme-definition.js";
+import type { ThemePackageConfig } from "./theme-package-config.js";
+
+export interface ThemeStylesheetInput {
+  theme: ThemeDefinition;
+  /** `@source` paths: relative to the written file, or absolute (a test compiling the sources in place). */
+  sources: readonly string[];
+  imports: readonly string[];
+}
+
+/**
+ * The text of a theme package's `theme.css`: the CSS imports, the component folders as `@source` (Tailwind resolves
+ * them relative to the file, so the app's Tailwind finds them inside `node_modules`), then the generated tokens.
+ */
+export function buildThemeStylesheet({ theme, sources, imports }: ThemeStylesheetInput): string {
+  return [
+    ...imports.map((name) => `@import ${JSON.stringify(name)};`),
+    ...sources.map((source) => `@source ${JSON.stringify(source)};`),
+    "",
+    buildThemeCss(theme),
+  ].join("\n");
+}
+
+export interface WriteThemeStylesheetsOptions {
+  /** The theme package's folder; its `src/` holds the stylesheets to copy. */
+  packageDir: string;
+  /** Where the files go; the package's `dist/` by default. */
+  distDir?: string;
+  theme: ThemeDefinition;
+  config: ThemePackageConfig;
+}
+
+/** Writes `theme.css` and copies the declared stylesheets; returns the written file names. */
+export function writeThemeStylesheets({ packageDir, distDir = join(packageDir, "dist"), theme, config }: WriteThemeStylesheetsOptions): string[] {
+  mkdirSync(distDir, { recursive: true });
+  writeFileSync(join(distDir, "theme.css"), buildThemeStylesheet({ theme, sources: config.sources, imports: config.imports }));
+  for (const name of config.stylesheets) copyFileSync(join(packageDir, "src", name), join(distDir, name));
+  return ["theme.css", ...config.stylesheets];
+}

package/src/build-theme-css.ts

@@ -0,0 +1,106 @@
+import { TOKEN_NAME, UNSAFE_VALUE } from "./check-theme.js";
+import { isColorAlias, type ThemeDefinition } from "./theme-definition.js";
+
+/** Light by default, and for an element or a page that asks for it. */
+const LIGHT_SELECTOR = ':root, .light, [data-theme="light"]';
+/** Dark by the system setting, unless the page asks for light. */
+const SYSTEM_DARK_SELECTOR = ':root:not(.light, [data-theme="light"])';
+/** Dark by choice: `next-themes` (`class="dark"`) or `@softure-ai/ui`'s theme switch (`data-theme="dark"`). */
+const DARK_SELECTOR = '.dark, [data-theme="dark"]';
+
+/**
+ * Tailwind's `dark:` variant on the same rule as the tokens: the system setting unless the page asks for light, or an
+ * explicit dark scope. Without it, `dark:` would follow only the system setting.
+ */
+const DARK_VARIANT = `@custom-variant dark {
+  @media (prefers-color-scheme: dark) {
+    &:where(${SYSTEM_DARK_SELECTOR}, ${SYSTEM_DARK_SELECTOR} *) {
+      @slot;
+    }
+  }
+  &:where(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *) {
+    @slot;
+  }
+}`;
+
+function checkName(kind: string, name: string): string {
+  if (!TOKEN_NAME.test(name)) throw new Error(`buildThemeCss: ${kind} name "${name}" is not a lowercase kebab-case name`);
+  return name;
+}
+
+function checkValue(name: string, value: string): string {
+  if (value.trim() === "" || UNSAFE_VALUE.test(value)) {
+    throw new Error(`buildThemeCss: value of "${name}" is empty or holds one of ; { } < > or a line break`);
+  }
+  return value;
+}
+
+function writeBlock(selector: string, lines: string[], indent = ""): string {
+  return [`${indent}${selector} {`, ...lines.map((line) => `${indent}  ${line}`), `${indent}}`].join("\n");
+}
+
+function writeSchemeLines(definition: ThemeDefinition, scheme: "light" | "dark"): string[] {
+  const colors = Object.entries(definition.colors).flatMap(([name, value]) => {
+    checkName("colour", name);
+    if (isColorAlias(value)) {
+      if (!(value.alias in definition.colors)) {
+        throw new Error(`buildThemeCss: colour "${name}" follows "${value.alias}", which the theme does not define`);
+      }
+      // An alias is a reference, so it follows its target's scheme without a dark line of its own.
+      return scheme === "light" ? [`--${name}: var(--${checkName("colour", value.alias)});`] : [];
+    }
+    return [`--${name}: ${checkValue(name, value[scheme])};`];
+  });
+  const shadows = Object.entries(definition.shadows).map(
+    ([name, value]) => `--shadow-${checkName("shadow", name)}: ${checkValue(`shadow-${name}`, value[scheme])};`,
+  );
+  return [...colors, ...shadows];
+}
+
+function writeThemeLines(definition: ThemeDefinition): string[] {
+  const lines: string[] = [];
+  if (definition.clearDefaultPalette) lines.push("--color-*: initial;");
+  for (const name of Object.keys(definition.colors)) lines.push(`--color-${name}: var(--${name});`);
+  for (const [family, stack] of Object.entries(definition.fonts)) {
+    lines.push(`--font-${checkName("font", family)}: ${checkValue(`font-${family}`, stack)};`);
+  }
+  for (const [name, style] of Object.entries(definition.textStyles)) {
+    const prefix = `--text-${checkName("text style", name)}`;
+    lines.push(`${prefix}: ${checkValue(prefix, style.fontSize)};`);
+    lines.push(`${prefix}--line-height: ${checkValue(prefix, style.lineHeight)};`);
+    lines.push(`${prefix}--font-weight: ${String(style.fontWeight)};`);
+    if (style.letterSpacing !== undefined) lines.push(`${prefix}--letter-spacing: ${checkValue(prefix, style.letterSpacing)};`);
+  }
+  for (const [step, value] of Object.entries(definition.radii)) {
+    lines.push(`--radius-${checkName("radius", step)}: ${checkValue(`radius-${step}`, value)};`);
+  }
+  // A themed shadow: the utility reads the scheme blocks' value, which the dark blocks switch.
+  for (const name of Object.keys(definition.shadows)) lines.push(`--shadow-${name}: var(--shadow-${name});`);
+  for (const [name, value] of Object.entries(definition.sizes)) {
+    lines.push(`--spacing-${checkName("size", name)}: ${checkValue(`spacing-${name}`, value)};`);
+  }
+  return lines;
+}
+
+/**
+ * The theme's CSS for Tailwind CSS v4: the tokens per scheme and the `@theme inline` block that turns them into
+ * utilities (`bg-background`, `text-page-title`, `rounded-xl`, `shadow-menu`, `w-sidebar-width`).
+ *
+ * Schemes: light on `:root` (and on `.light`, `[data-theme="light"]`); dark by the system setting unless the page asks
+ * for light, and on `.dark`, `[data-theme="dark"]`, so `next-themes` and `@softure-ai/ui`'s theme switch both work,
+ * and a section can take a fixed scheme; Tailwind's `dark:` variant follows the same rule. Throws on a name that is not kebab-case, an unsafe value, or an alias of an
+ * undefined colour.
+ */
+export function buildThemeCss(definition: ThemeDefinition): string {
+  const light = writeSchemeLines(definition, "light");
+  const dark = writeSchemeLines(definition, "dark");
+  return [
+    `/* Theme "${definition.name.replace(/\*\//g, "")}", generated by @softure-ai/theme-kit (buildThemeCss). */`,
+    DARK_VARIANT,
+    writeBlock(LIGHT_SELECTOR, light),
+    `@media (prefers-color-scheme: dark) {\n${writeBlock(SYSTEM_DARK_SELECTOR, dark, "  ")}\n}`,
+    writeBlock(DARK_SELECTOR, dark),
+    writeBlock("@theme inline", writeThemeLines(definition)),
+    "",
+  ].join("\n\n");
+}

package/src/check-theme.ts

@@ -0,0 +1,62 @@
+import { findMissingColorRoles, isColorAlias, type ThemeDefinition } from "./theme-definition.js";
+
+/** A token name: lowercase kebab-case (`primary-hover`, `chart-1`). */
+export const TOKEN_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Characters that would end a CSS declaration or block, or open markup. */
+export const UNSAFE_VALUE = /[;{}<>\r\n]/;
+
+function findNameProblems(kind: string, names: readonly string[]): string[] {
+  return names.filter((name) => !TOKEN_NAME.test(name)).map((name) => `${kind} name "${name}" is not a lowercase kebab-case name`);
+}
+
+function findValueProblems(entries: readonly (readonly [string, string])[]): string[] {
+  return entries
+    .filter(([, value]) => value.trim() === "" || UNSAFE_VALUE.test(value))
+    .map(([name]) => `value of "${name}" is empty or holds one of ; { } < > or a line break`);
+}
+
+function listValues(definition: ThemeDefinition): (readonly [string, string])[] {
+  const colors = Object.entries(definition.colors).flatMap(([name, value]) =>
+    isColorAlias(value) ? [] : [[name, value.light] as const, [name, value.dark] as const],
+  );
+  const shadows = Object.entries(definition.shadows).flatMap(([name, value]) => [
+    [`shadow-${name}`, value.light] as const,
+    [`shadow-${name}`, value.dark] as const,
+  ]);
+  const fonts = Object.entries(definition.fonts).map(([family, stack]) => [`font-${family}`, stack] as const);
+  const textStyles = Object.entries(definition.textStyles).flatMap(([name, style]) =>
+    [style.fontSize, style.lineHeight, ...(style.letterSpacing === undefined ? [] : [style.letterSpacing])].map(
+      (value) => [`text-${name}`, value] as const,
+    ),
+  );
+  const radii = Object.entries(definition.radii).map(([step, value]) => [`radius-${step}`, value] as const);
+  const sizes = Object.entries(definition.sizes).map(([name, value]) => [`spacing-${name}`, value] as const);
+  return [...colors, ...shadows, ...fonts, ...textStyles, ...radii, ...sizes];
+}
+
+/**
+ * Every way a definition breaks the theme contract, as readable messages; empty when the theme is complete. Checks the
+ * shadcn colour roles, that every token name is kebab-case, that no value is empty or could break out of the CSS, and
+ * that every alias points at a colour of the same theme.
+ */
+export function checkTheme(definition: ThemeDefinition): string[] {
+  const problems: string[] = [];
+  if (definition.name.trim() === "") problems.push("the theme has no name");
+  const missing = findMissingColorRoles(definition);
+  if (missing.length > 0) problems.push(`missing shadcn colour roles: ${missing.join(", ")}`);
+  problems.push(
+    ...findNameProblems("colour", Object.keys(definition.colors)),
+    ...findNameProblems("shadow", Object.keys(definition.shadows)),
+    ...findNameProblems("font", Object.keys(definition.fonts)),
+    ...findNameProblems("text style", Object.keys(definition.textStyles)),
+    ...findNameProblems("radius", Object.keys(definition.radii)),
+    ...findNameProblems("size", Object.keys(definition.sizes)),
+    ...findValueProblems(listValues(definition)),
+  );
+  for (const [name, value] of Object.entries(definition.colors)) {
+    if (isColorAlias(value) && !(value.alias in definition.colors)) {
+      problems.push(`colour "${name}" follows "${value.alias}", which the theme does not define`);
+    }
+  }
+  return problems;
+}

package/src/cli/command.ts

@@ -0,0 +1,33 @@
+import { resolve } from "node:path";
+
+import { buildThemePackage } from "../build/build-theme-package.js";
+
+export interface ThemeCssCommandInput {
+  argv: readonly string[];
+  cwd: string;
+  write?: (line: string) => void;
+  writeError?: (line: string) => void;
+}
+
+const USAGE = "Usage: softure-theme-css [packageDir]   (default: the current folder, after tsc)";
+
+/** `softure-theme-css [packageDir]`: builds a theme package's stylesheets; returns the exit code. */
+export async function runThemeCssCommand({
+  argv,
+  cwd,
+  write = (line) => console.log(line),
+  writeError = (line) => console.error(line),
+}: ThemeCssCommandInput): Promise<number> {
+  if (argv.length > 1 || argv[0] === "--help" || argv[0] === "-h") {
+    writeError(USAGE);
+    return argv.length > 1 ? 1 : 0;
+  }
+  const packageDir = resolve(cwd, argv[0] ?? ".");
+  const result = await buildThemePackage(packageDir);
+  if (!result.ok) {
+    writeError(`softure-theme-css: ${result.error}`);
+    return 1;
+  }
+  write(`softure-theme-css: ${result.files.join(", ")} in ${resolve(packageDir, "dist")}`);
+  return 0;
+}

package/src/create-cn.ts

@@ -0,0 +1,31 @@
+import { clsx, type ClassValue } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+import type { ThemeDefinition } from "./theme-definition.js";
+
+export type { ClassValue } from "clsx";
+
+export interface CnOptions {
+  /** The theme's named text styles, so `text-body` (a size) and `text-muted-foreground` (a colour) both stay. */
+  textStyles?: readonly string[];
+  /** The theme's named shadows, so a later `shadow-card` replaces an earlier `shadow-menu`. */
+  shadows?: readonly string[];
+}
+
+export type Cn = (...inputs: ClassValue[]) => string;
+
+/**
+ * shadcn/ui's `cn` for a theme: joins class names and lets a later Tailwind utility win over an earlier one of the
+ * same kind, knowing the theme's own text styles and shadows.
+ */
+export function createCn({ textStyles = [], shadows = [] }: CnOptions = {}): Cn {
+  const mergeClasses = extendTailwindMerge({
+    extend: { theme: { text: [...textStyles], shadow: [...shadows] } },
+  });
+  return (...inputs) => mergeClasses(clsx(inputs));
+}
+
+/** `createCn` with the text styles and shadows a theme definition names. */
+export function createThemeCn(definition: Pick<ThemeDefinition, "textStyles" | "shadows">): Cn {
+  return createCn({ textStyles: Object.keys(definition.textStyles), shadows: Object.keys(definition.shadows) });
+}

package/src/define-theme.ts

@@ -0,0 +1,15 @@
+import { checkTheme } from "./check-theme.js";
+import type { ThemeDefinition } from "./theme-definition.js";
+
+/**
+ * Declares a theme: checks it against the contract (`checkTheme`) and returns it unchanged, with its literal types, so
+ * a broken theme fails where it is written, at import time, not when its CSS is generated. Throws with every problem
+ * listed.
+ */
+export function defineTheme<const T extends ThemeDefinition>(definition: T): T {
+  const problems = checkTheme(definition);
+  if (problems.length > 0) {
+    throw new Error(`defineTheme: theme "${definition.name}" breaks the theme contract:\n- ${problems.join("\n- ")}`);
+  }
+  return definition;
+}

package/src/extend-theme.ts

@@ -0,0 +1,33 @@
+import { defineTheme } from "./define-theme.js";
+import type { ThemeDefinition } from "./theme-definition.js";
+
+/** What a variant changes: a new name, and per token group only the tokens it adds or replaces. */
+export interface ThemeOverrides {
+  name: string;
+  colors?: ThemeDefinition["colors"];
+  shadows?: ThemeDefinition["shadows"];
+  fonts?: ThemeDefinition["fonts"];
+  textStyles?: ThemeDefinition["textStyles"];
+  radii?: ThemeDefinition["radii"];
+  sizes?: ThemeDefinition["sizes"];
+  clearDefaultPalette?: boolean;
+}
+
+/**
+ * A theme built on another: each token group of `overrides` is laid over the base's group (a token is replaced
+ * whole, never merged field by field), the rest is the base's. Used for a theme that differs from an existing one in
+ * a few tokens, and by an app that generates its own variant with `buildThemeCss`. The result is checked like
+ * `defineTheme`.
+ */
+export function extendTheme(base: ThemeDefinition, overrides: ThemeOverrides): ThemeDefinition {
+  return defineTheme({
+    name: overrides.name,
+    colors: { ...base.colors, ...overrides.colors },
+    shadows: { ...base.shadows, ...overrides.shadows },
+    fonts: { ...base.fonts, ...overrides.fonts },
+    textStyles: { ...base.textStyles, ...overrides.textStyles },
+    radii: { ...base.radii, ...overrides.radii },
+    sizes: { ...base.sizes, ...overrides.sizes },
+    clearDefaultPalette: overrides.clearDefaultPalette ?? base.clearDefaultPalette,
+  });
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  SHADCN_COLOR_ROLES,
+  findMissingColorRoles,
+  isColorAlias,
+  type ColorAlias,
+  type ColorValue,
+  type SchemeValue,
+  type ShadcnColorRole,
+  type TextStyle,
+  type ThemeDefinition,
+} from "./theme-definition.js";
+export { checkTheme } from "./check-theme.js";
+export { defineTheme } from "./define-theme.js";
+export { extendTheme, type ThemeOverrides } from "./extend-theme.js";
+export { buildThemeCss } from "./build-theme-css.js";
+export { createCn, createThemeCn, type ClassValue, type Cn, type CnOptions } from "./create-cn.js";

package/src/preflight.css

@@ -0,0 +1,77 @@
+/*
+ * Tailwind CSS v4's preflight, scoped to design-system elements: every shadcn/ui part carries `data-slot`, so a
+ * screen root with a `data-slot` brings the reset to everything inside it, while pages drawn by other packages (on
+ * `@softure-ai/ui`'s own base) keep theirs. Import it instead of Tailwind's `preflight.css` when the app mixes both;
+ * an app that is all design system can take Tailwind's full preflight instead.
+ *
+ * Reads `--border`, `--ring` and `--muted-foreground` from the theme. Also turns transitions and animations off under
+ * `prefers-reduced-motion`.
+ */
+@layer base {
+  :where([data-slot], [data-slot] *),
+  :where([data-slot], [data-slot] *)::before,
+  :where([data-slot], [data-slot] *)::after,
+  :where([data-slot], [data-slot] *)::backdrop {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+    border: 0 solid var(--border);
+  }
+
+  :where([data-slot], [data-slot] *) {
+    outline-color: color-mix(in oklab, var(--ring) 50%, transparent);
+  }
+
+  :where(h1, h2, h3, h4, h5, h6):where([data-slot], [data-slot] *) {
+    font-size: inherit;
+    font-weight: inherit;
+  }
+
+  :where(a):where([data-slot], [data-slot] *) {
+    color: inherit;
+    text-decoration: inherit;
+  }
+
+  :where(ol, ul, menu):where([data-slot], [data-slot] *) {
+    list-style: none;
+  }
+
+  :where(img, svg, video, canvas):where([data-slot], [data-slot] *) {
+    display: block;
+    vertical-align: middle;
+  }
+
+  :where(table):where([data-slot], [data-slot] *) {
+    border-collapse: collapse;
+    text-indent: 0;
+  }
+
+  :where(button, input, select, optgroup, textarea):where([data-slot], [data-slot] *) {
+    font: inherit;
+    letter-spacing: inherit;
+    color: inherit;
+    background-color: transparent;
+    border-radius: 0;
+    opacity: 1;
+  }
+
+  :where(button, [role="button"]):where([data-slot], [data-slot] *):not(:disabled) {
+    cursor: pointer;
+  }
+
+  :where(textarea):where([data-slot], [data-slot] *) {
+    resize: vertical;
+  }
+
+  :where(::placeholder):where([data-slot], [data-slot] *) {
+    opacity: 1;
+    color: var(--muted-foreground);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    :where([data-slot], [data-slot] *) {
+      transition-duration: 0s !important;
+      animation-duration: 0s !important;
+    }
+  }
+}

package/src/react/index.ts

@@ -0,0 +1 @@
+export { MOBILE_BREAKPOINT, useIsMobile } from "./use-is-mobile.js";

package/src/react/use-is-mobile.ts

@@ -0,0 +1,29 @@
+import * as React from "react";
+
+/** The width below which shadcn/ui's sidebar turns into a sheet. */
+export const MOBILE_BREAKPOINT = 768;
+
+const MOBILE_QUERY = `(max-width: ${MOBILE_BREAKPOINT - 1}px)`;
+
+function subscribeToViewport(onChange: () => void): () => void {
+  const query = window.matchMedia(MOBILE_QUERY);
+  query.addEventListener("change", onChange);
+  return () => query.removeEventListener("change", onChange);
+}
+
+function isMobileViewport(): boolean {
+  return window.matchMedia(MOBILE_QUERY).matches;
+}
+
+// The server renders the desktop layout; the browser switches on hydration.
+function isMobileOnServer(): boolean {
+  return false;
+}
+
+/**
+ * Whether the viewport is narrower than `MOBILE_BREAKPOINT` (shadcn/ui's `useIsMobile`, read through
+ * `useSyncExternalStore` instead of a state set inside an effect).
+ */
+export function useIsMobile(): boolean {
+  return React.useSyncExternalStore(subscribeToViewport, isMobileViewport, isMobileOnServer);
+}

package/src/theme-definition.ts

@@ -0,0 +1,92 @@
+/** A colour or shadow with one value per colour scheme. */
+export interface SchemeValue {
+  light: string;
+  dark: string;
+}
+
+/** A colour that follows another token of the same theme in both schemes (`chart-1` → `blue`). */
+export interface ColorAlias {
+  alias: string;
+}
+
+export type ColorValue = SchemeValue | ColorAlias;
+
+/** A named text style: `text-<name>` sets the size, line height, weight and tracking at once. */
+export interface TextStyle {
+  fontSize: string;
+  lineHeight: string;
+  fontWeight: number;
+  letterSpacing?: string;
+}
+
+/**
+ * Everything a theme decides, as plain data. `buildThemeCss` turns it into the theme's CSS; a theme package keeps
+ * one definition and ships the generated file.
+ */
+export interface ThemeDefinition {
+  /** The theme's name, written into the generated file's header. */
+  name: string;
+  /** Colour tokens by name (`background`, `primary`, `green-tag`), utilities `bg-<name>`, `text-<name>`. */
+  colors: Record<string, ColorValue>;
+  /** Shadows by name without the prefix (`menu` → `--shadow-menu`, `shadow-menu`). */
+  shadows: Record<string, SchemeValue>;
+  /** Font stacks by family (`sans` → `font-sans`). */
+  fonts: Record<string, string>;
+  /** Named text styles (`page-title` → `text-page-title`). */
+  textStyles: Record<string, TextStyle>;
+  /** Radii by step (`md` → `rounded-md`). */
+  radii: Record<string, string>;
+  /** Layout sizes as spacing values (`sidebar-width` → `w-sidebar-width`). */
+  sizes: Record<string, string>;
+  /** Clears Tailwind's default palette, so only the theme's colours exist as utilities. */
+  clearDefaultPalette: boolean;
+}
+
+/**
+ * The colour roles shadcn/ui components read. Every theme defines them, so a component written for one theme renders
+ * in another; a theme adds its own tokens on top.
+ */
+export const SHADCN_COLOR_ROLES = [
+  "background",
+  "foreground",
+  "card",
+  "card-foreground",
+  "popover",
+  "popover-foreground",
+  "primary",
+  "primary-foreground",
+  "secondary",
+  "secondary-foreground",
+  "muted",
+  "muted-foreground",
+  "accent",
+  "accent-foreground",
+  "destructive",
+  "border",
+  "input",
+  "ring",
+  "chart-1",
+  "chart-2",
+  "chart-3",
+  "chart-4",
+  "chart-5",
+  "sidebar",
+  "sidebar-foreground",
+  "sidebar-primary",
+  "sidebar-primary-foreground",
+  "sidebar-accent",
+  "sidebar-accent-foreground",
+  "sidebar-border",
+  "sidebar-ring",
+] as const;
+
+export type ShadcnColorRole = (typeof SHADCN_COLOR_ROLES)[number];
+
+/** The shadcn colour roles a definition lacks, in contract order; empty when it is complete. */
+export function findMissingColorRoles(definition: Pick<ThemeDefinition, "colors">): ShadcnColorRole[] {
+  return SHADCN_COLOR_ROLES.filter((role) => !(role in definition.colors));
+}
+
+export function isColorAlias(value: ColorValue): value is ColorAlias {
+  return "alias" in value;
+}