@sanity/themer 0.1.0 → 0.2.0

package/README.md

@@ -1,15 +1,70 @@
 # @sanity/themer
 
-Recreate [Sanity Studio](https://www.sanity.io/studio) themes from the hosted Themer service locally.
-
-This package is the npm migration path off the hosted Themer service ([themer.sanity.build](https://themer.sanity.build)) — the generator runs locally, so Studio configs no longer need to import modules from a hosted URL. The `@sanity/themer/legacy` subpath generates the exact same colors the service serves. There is no root export yet.
+Generate [Sanity Studio](https://www.sanity.io/studio) themes from a handful of colors.
 
 ```sh
 npm install @sanity/themer
 ```
 
+## Usage
+
+`buildTheme` builds the same type of theme as `buildTheme` from `@sanity/ui/theme` — ready for the `theme` property of a Studio config — but takes colors instead of design tokens. Under the hood it only swaps out the color palette that `@sanity/ui/theme` otherwise fills with [`@sanity/color`](https://www.sanity.io/docs/color):
+
+```ts
+import {buildTheme} from '@sanity/themer'
+import {defineConfig} from 'sanity'
+
+export const theme = buildTheme({
+  accent: '#f00', // required
+  text: '#727892', // optional
+  background: {dark: '#0d0e12', light: '#ffffff'}, // optional
+  contrast: 85, // optional, 15–100
+})
+
+export default defineConfig({
+  theme,
+  // ...rest of the config
+})
+```
+
+- `accent` replaces the `blue` scale of the palette, which Sanity UI uses for primary buttons, focus rings and links.
+- `text` replaces the `gray` scale — text, icons, borders and neutral surfaces. When omitted it is derived from `accent`: a mostly desaturated version of it, the way the stock gray carries a hint of the stock blue.
+- `background.dark` replaces `black` and `background.light` replaces `white` — the backgrounds of the two color schemes that every other color blends onto.
+- `contrast` controls how strongly text and borders separate from the accent. The default `85` uses the text color as-is; `100` removes its tint entirely (a high contrast scheme with no mixing of text and accent), and lower values blend more and more of the accent into the text scale, giving text and borders more color.
+
+A few ground rules keep the generated palette usable: the accent and text colors cannot be too dark or too light (they would mess with the rest of their scales), `background.dark` is made darker until it has enough contrast with both of them (it can never be lighter than either), and `background.light` can never be darker than either.
+
+Called with the stock colors — like `text` and `background` in the example — the generated colors match `buildTheme()` from `@sanity/ui/theme` with no options exactly.
+
+`buildPalette` returns the generated `@sanity/color`-shaped palette without building a theme from it, and `presets` ships the hosted Themer service presets translated to `buildTheme` options:
+
+```ts
+import {buildTheme, presets} from '@sanity/themer'
+
+const verdant = presets.find((preset) => preset.slug === 'verdant')
+const theme = buildTheme(verdant.options)
+```
+
+## Studio tool
+
+`@sanity/themer/tool` adds a themer sidebar to the Studio for these themes: presets, accent/text/background pickers and a contrast slider preview a `buildTheme` theme live on the whole Studio, plus the snippet to make it permanent:
+
+```ts
+import {themerTool} from '@sanity/themer/tool'
+import {defineConfig} from 'sanity'
+
+export default defineConfig({
+  plugins: [themerTool()],
+  // ...rest of the config
+})
+```
+
+If the Studio already uses a `buildTheme` theme, pass the same options so the tool starts editing from them: `themerTool({config: {accent: '#1cb485'}})`.
+
 ## Migrating from themer.sanity.build
 
+This package is also the npm migration path off the hosted Themer service ([themer.sanity.build](https://themer.sanity.build)) — the generator runs locally, so Studio configs no longer need to import modules from a hosted URL.
+
 `@sanity/themer/legacy` generates the exact same colors as the hosted service, with the same `createTheme`, `hues` and `theme` exports that `https://themer.sanity.build/api/hues` served. Replace the URL import with `buildThemeFromUrl` and the URL as a string:
 
 ```ts

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import { t as BuildThemeOptions } from "./options-BaqJJgRs.js";
+import { ColorHueKey, ColorTintKey } from "@sanity/color";
+import { RootTheme } from "@sanity/ui/theme";
+/**
+ * The color palette generated by {@link buildPalette}: the `palette` config
+ * of `buildTheme` from `@sanity/ui/theme`, with every color as a hex string.
+ *
+ * @public
+ */
+type GeneratedColorPalette = {
+  black: string;
+  white: string;
+} & Record<ColorHueKey, Record<ColorTintKey, string>>;
+/**
+ * Generates a Sanity UI color palette from the theme options: the accent
+ * color replaces the `blue` scale, the text color the `gray` scale, and the
+ * backgrounds replace `black` and `white`. All other hues keep their stock
+ * `@sanity/color` values. Called with the stock colors, it returns the stock
+ * palette byte-for-byte.
+ *
+ * ```ts
+ * import {buildPalette} from '@sanity/themer'
+ *
+ * const palette = buildPalette({accent: '#556bfc'})
+ * ```
+ *
+ * @public
+ */
+declare function buildPalette(options: BuildThemeOptions): GeneratedColorPalette;
+/**
+ * Generates a Studio theme from a handful of colors, by replacing the color
+ * palette that the `buildTheme` from `@sanity/ui/theme` otherwise fills with
+ * `@sanity/color`: the accent color replaces the `blue` scale (primary
+ * buttons, focus rings, links), the optional text color the `gray` scale
+ * (text, icons, borders), and the optional backgrounds replace `black` and
+ * `white`. The result is the same type of theme that `@sanity/ui/theme`
+ * builds, ready for the `theme` property of a Studio config.
+ *
+ * ```ts
+ * import {buildTheme} from '@sanity/themer'
+ * import {defineConfig} from 'sanity'
+ *
+ * export const theme = buildTheme({
+ *   accent: '#556bfc',
+ *   text: '#727892', // optional — derived from `accent` when omitted
+ *   background: {dark: '#0d0e12', light: '#ffffff'}, // optional
+ *   contrast: 85, // optional, 15–100
+ * })
+ *
+ * export default defineConfig({
+ *   theme,
+ *   // ...rest of the config
+ * })
+ * ```
+ *
+ * Called with the stock colors — like the example — it returns the exact
+ * same colors as `buildTheme()` from `@sanity/ui/theme` with no options.
+ *
+ * @public
+ */
+declare function buildTheme(options: BuildThemeOptions): RootTheme;
+/**
+ * A preset theme: a named set of {@link BuildThemeOptions} ready to pass to
+ * `buildTheme`.
+ *
+ * @public
+ */
+interface ThemePreset {
+  slug: string;
+  title: string;
+  /** The preset's theme options, ready to pass to `buildTheme` */
+  options: BuildThemeOptions;
+}
+/**
+ * Preset themes for `buildTheme`, carried over from the hosted Themer service
+ * (themer.sanity.build) presets: each one maps the legacy preset's primary
+ * hue to `accent`, its default hue to `text` and its lightest/darkest colors
+ * to the backgrounds.
+ *
+ * ```ts
+ * import {buildTheme, presets} from '@sanity/themer'
+ *
+ * const verdant = presets.find((preset) => preset.slug === 'verdant')
+ * const theme = buildTheme(verdant.options)
+ * ```
+ *
+ * @public
+ */
+declare const presets: ThemePreset[];
+export { type BuildThemeOptions, type GeneratedColorPalette, type ThemePreset, buildPalette, buildTheme, presets };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/theme/buildPalette.ts","../src/theme/buildTheme.ts","../src/theme/presets.ts"],"mappings":";;;;;;;;;KAqCY;EAAyB;EAAe;IAAiB,OACnE,aACA,OAAO;;;;;;;;;;;;;;;;iBAkBO,aAAa,SAAS,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBCrB1C,WAAW,SAAS,oBAAoB;;;;;;;UC5BvC;EACf;EACA;;EAEA,SAAS;;;;;;;;;;;;;;;;;cAkBE,SAAS"}

package/dist/index.js

@@ -0,0 +1,2 @@
+import { n as buildTheme, r as buildPalette, t as presets } from "./presets-DWzYcsLg.js";
+export { buildPalette, buildTheme, presets };

package/dist/legacy.d.ts

@@ -1,4 +1,75 @@
-import { a as PartialHues, i as LegacyTheme, n as HueMidPoint, o as ThemePreset, r as Hues, t as Hue } from "./types-DfPLuLv0.js";
+import { RootTheme } from "@sanity/ui/theme";
+/**
+ * The tint (between 50 and 950) that a `Hue`'s `mid` color is placed at.
+ *
+ * @public
+ */
+type HueMidPoint = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950;
+/**
+ * A single hue configuration, matching the hosted Themer service
+ * (themer.sanity.build) hue format.
+ *
+ * @public
+ */
+interface Hue {
+  /** The mid color of the hue's tint ramp, as a hex color */
+  mid: string;
+  /** The tint that `mid` is placed at — the rest of the ramp is interpolated */
+  midPoint: HueMidPoint;
+  /** The hex color that the ramp's lightest end interpolates towards */
+  lightest: string;
+  /** The hex color that the ramp's darkest end interpolates towards */
+  darkest: string;
+}
+/**
+ * The six hues a legacy Themer theme is generated from.
+ *
+ * @public
+ */
+interface Hues {
+  default: Hue;
+  transparent: Hue;
+  primary: Hue;
+  positive: Hue;
+  caution: Hue;
+  critical: Hue;
+}
+/**
+ * `Hues` where every hue, and every property of each hue, is optional.
+ * Omitted properties fall back to the default Studio theme hues.
+ *
+ * @public
+ */
+type PartialHues = { [TKey in keyof Hues]?: Partial<Hues[TKey]>; };
+/**
+ * A theme generated by `createTheme`, compatible with the `theme` property in
+ * a Sanity Studio `defineConfig`.
+ *
+ * @public
+ */
+type LegacyTheme = RootTheme & {
+  /**
+   * Set to `undefined` so that `@sanity/ui` derives the v2 theme internally
+   * from the generated colors.
+   */
+  v2: undefined;
+};
+/**
+ * A preset theme, carried over from the hosted Themer service.
+ *
+ * @public
+ */
+interface ThemePreset {
+  slug: string;
+  title: string;
+  /**
+   * The canonical search params for this preset — the same query that
+   * `https://themer.sanity.build/api/hues` served the preset for.
+   */
+  searchParams: string;
+  /** The preset's resolved hues, ready to pass to `createTheme` */
+  hues: Hues;
+}
 /**
  * Generates a Studio theme from hues, producing the same colors as importing
  * the theme from the hosted Themer service (themer.sanity.build):

package/dist/legacy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legacy.d.ts","names":[],"sources":["../src/legacy/createTheme.ts","../src/legacy/defaults.ts","../src/legacy/presets.ts"],"mappings":";;;;;;;;;;;;;;;;;iBAsBgB,YAAY,OAAM,cAAmB;;;;;;;;;;;;;;;;;iBAoBrC,iBAAiB,cAAc,MAAM;;;;;;;;;;;;;;;;;;;iBAyBrC,kBAAkB,cAAc,MAAM;;;;;;;cCzDzC,MAAM;;;;;;;cAQN,OAAO;;;;;;;;;;;;;;cCcP,SAAS"}
+{"version":3,"file":"legacy.d.ts","names":[],"sources":["../src/legacy/types.ts","../src/legacy/createTheme.ts","../src/legacy/defaults.ts","../src/legacy/presets.ts"],"mappings":";;;;;;KAOY;;;;;;;UAQK;;EAEf;;EAEA,UAAU;;EAEV;;EAEA;;;;;;;UAQe;EACf,SAAS;EACT,aAAa;EACb,SAAS;EACT,UAAU;EACV,SAAS;EACT,UAAU;;;;;;;;KASA,iBAAgB,cAAc,QAAQ,QAAQ,KAAK;;;;;;;KAQnD,cAAc;;;;;EAKxB;;;;;;;UAQe;EACf;EACA;;;;;EAKA;;EAEA,MAAM;;;;;;;;;;;;;;;;;;iBCtDQ,YAAY,OAAM,cAAmB;;;;;;;;;;;;;;;;;iBAoBrC,iBAAiB,cAAc,MAAM;;;;;;;;;;;;;;;;;;;iBAyBrC,kBAAkB,cAAc,MAAM;;;;;;;cCzDzC,MAAM;;;;;;;cAQN,OAAO;;;;;;;;;;;;;;cCcP,SAAS"}