@greese/ui 1.1.0 → 1.2.0

package/dist/themeFiles/spec.d.ts

@@ -0,0 +1,198 @@
+/**
+ * A theme as data: plain JSON, the file Theme Studio (or any other tool)
+ * reads and writes. `specToLayout()` turns it into a folder of SCSS modules
+ * that use the SCSS kit (`pkg:@greese/ui/scss/kit`), to keep in your source
+ * and edit a part at a time; `specToScss()` into one file. Either compiles
+ * exactly like a theme written by hand. Pure: Node and the browser both use
+ * it (`@greese/ui/theme-files`).
+ */
+import { type ShapeDef, type ShapeSize } from '../shapes.ts';
+/** One value for both schemes, or a light/dark pair. */
+export type SchemeValue = string | {
+    light: string;
+    dark: string;
+};
+/** CSS declarations: `{ 'font-weight': '700' }`. */
+export type Declarations = Record<string, string>;
+export interface MotionSpec {
+    /** An effect that ends at rest, kebab-case: `fade-up`, or one of the theme's own. */
+    enter?: string;
+    /** Your own `@keyframes` name, instead of a preset. */
+    keyframes?: string;
+    /** An overlay exit, kebab-case: `fade-out`, `scale-out`, or one of the theme's own. */
+    exit?: string;
+    duration?: string;
+    delay?: string;
+    ease?: string;
+    distance?: string;
+    /** Transition speeds for this component: `{ fast: '80ms' }`. */
+    durations?: Record<string, string>;
+    /** Transition curves for this component: `{ standard: 'linear' }`. */
+    easings?: Record<string, string>;
+}
+export interface ComponentSpec {
+    /** Declarations on the component's root class. */
+    styles?: Declarations;
+    /** Component variables and tokens, without `--greese-`: `{ 'button-tone': '…' }`. */
+    vars?: Record<string, SchemeValue>;
+    /** Declarations per modifier: `{ outline: { 'border-width': '2px' } }`. */
+    modifiers?: Record<string, Declarations>;
+    /** Declarations per part: `{ icon: { opacity: '0.8' } }`. */
+    parts?: Record<string, Declarations>;
+    /**
+     * The SCSS of this component and what it contains (ADR 0021): leading `@use`
+     * lines, then a body written inside `.greese-<Name>` (`&`, nesting, mixins,
+     * the kit). The Studio starts it from the library's own SCSS for the family;
+     * it is stored only once edited, and then applies in full, inside this
+     * component only.
+     */
+    scss?: string;
+    motion?: MotionSpec;
+    /** One of the theme's shapes (`shapes`), by name: its outline, border and motion. */
+    shape?: string;
+}
+/**
+ * An effect's keyframes, as greese.js takes them and the theme's JSON holds
+ * them: a list of frames, or property → values.
+ */
+export type ThemeKeyframes = ReadonlyArray<Record<string, unknown>> | Record<string, unknown>;
+/**
+ * An effect the theme defines: its keyframes (greese.js's), and how long it
+ * runs. A tool that knows greese.js's types narrows `K` to its `Keyframes`.
+ */
+export interface EffectSpec<K extends ThemeKeyframes = ThemeKeyframes> {
+    keyframes: K;
+    /** Seconds. Without one, the effect takes the instance's, else 0.5. */
+    duration?: number;
+}
+/**
+ * A selector rule for page transitions (ADR 0029; the kit's
+ * `page-transitions()`): `'still'` keeps the elements in place, or their own
+ * `enter` (an entrance) and `exit` (an exit) by kebab-case name or `none`,
+ * `duration` (a token or a time), `delay` and `ease`. What it leaves out
+ * follows the theme's page roles.
+ */
+export type PageRuleSpec = 'still' | Partial<Record<'enter' | 'exit' | 'duration' | 'delay' | 'ease', string>>;
+/** What a page rule can set. */
+export declare const PAGE_RULE_KEYS: readonly ["enter", "exit", "duration", "delay", "ease"];
+export interface ThemeSpec<K extends ThemeKeyframes = ThemeKeyframes> {
+    /**
+     * Scope to `data-greese-theme="<name>"` (a complete theme, as
+     * `createTheme`). Empty: change the page's defaults.
+     */
+    name?: string;
+    /** Token overrides by group, kebab-case: `{ color: { accent: … }, radius: { md: '12px' } }`. */
+    tokens?: Record<string, Record<string, SchemeValue>>;
+    /**
+     * The breakpoints the stylesheet is built with, key to min-width in px:
+     * every key (the five built-in ones stay; added ones are new), smallest
+     * first. Absent means the defaults. Setting them makes the studio build the
+     * whole stylesheet, since the media queries are fixed in it.
+     */
+    breakpoints?: Record<string, number>;
+    /**
+     * The type system by variant, then `base` or a breakpoint, then property:
+     * `{ h1: { base: { size: '2rem' }, lg: { size: '4rem' } } }`.
+     */
+    typography?: Record<string, Record<string, Record<string, string>>>;
+    /** Tunes every `greese` prop entrance: duration, delay, ease, distance. */
+    motionDefaults?: Record<string, string>;
+    /** Parts of a page with page-transition motion of their own, by selector. */
+    pageRules?: Record<string, PageRuleSpec>;
+    /**
+     * Effects by camelCase name. A built-in's name retunes it (a preset's
+     * `@keyframes` are overridden in the theme's CSS, and every effect is
+     * defined for the runtime); any other name adds a new effect.
+     */
+    effects?: Record<string, EffectSpec<K>>;
+    /** Overrides by component name: `{ Button: { … } }`. */
+    components?: Record<string, ComponentSpec>;
+    /**
+     * Shapes by kebab-case name (ADR 0024): each is a `greese-shape-<name>`
+     * class for any element, and components take one with `shape`.
+     */
+    shapes?: Record<string, ShapeDef>;
+}
+export declare const emptySpec: () => ThemeSpec;
+/** The breakpoints in effect, smallest first: the theme's, else the defaults. */
+export declare const breakpointsOf: (spec: ThemeSpec) => Array<[string, number]>;
+/** The theme's own breakpoints, if they differ from the defaults. */
+export declare const customBreakpoints: (spec: ThemeSpec) => Array<[string, number]> | undefined;
+/** Problems that would make the generated SCSS unsafe or invalid. */
+export declare const validateSpec: (spec: ThemeSpec) => string[];
+/**
+ * A token the theme adds: its group exists but the system has no token of
+ * that name. (A group that doesn't exist stays an override, so the kit
+ * reports it.)
+ */
+export declare const isCustomToken: (group: string, key: string) => boolean;
+/** The line that builds the stylesheet (or just its settings) with these breakpoints. */
+export declare const stylesheetScss: (breakpoints: Array<[string, number]>, entry?: "stylesheet" | "config") => string;
+/**
+ * The theme as SCSS for the kit. Output is stable (sorted components) so the
+ * file diffs cleanly in version control.
+ */
+export declare const specToScss: (spec: ThemeSpec, source?: string, 
+/** How the stylesheet is brought in: whole (the output), or just its settings. */
+entry?: "stylesheet" | "config") => string;
+/** Where a line of the generated theme came from: a component's SCSS box, and its line there. */
+export interface LineOrigin {
+    component: string;
+    line: number;
+}
+/**
+ * `specToScss`, and which component's SCSS each line of it came from, so a
+ * Sass error in the generated file points back at the box and line you wrote.
+ */
+export declare const specToScssWithLines: (spec: ThemeSpec, source?: string, entry?: "stylesheet" | "config") => {
+    scss: string;
+    origin: (line: number) => LineOrigin | undefined;
+};
+/**
+ * The theme's shapes (ADR 0024): their parameters registered, a
+ * `greese-shape-<name>` class for each, and the components that take one.
+ * Written by @greese/ui/shapes, the same code the Studio's editor previews
+ * with; each selector goes through the kit's `themed()`, which scopes it to
+ * the theme (`scope`, a Sass expression for its name) and, for a component,
+ * guards it for the shape layer, so `.greese-reset-shape` and `reset(shape)`
+ * reach shapes too.
+ */
+export declare const shapesScss: (spec: ThemeSpec, scope?: string, size?: ShapeSize) => string;
+/**
+ * The first line of every file `specToLayout()` writes. A tool that rewrites
+ * the layout leaves a file alone once this line is gone: whoever deleted it
+ * maintains that file by hand now.
+ */
+export declare const LAYOUT_MARK = "// greese-theme: generated";
+/**
+ * The theme as a folder of SCSS modules, by path inside the folder. Each file
+ * is a Sass module that writes its own CSS when it is loaded, so a component,
+ * a token group or the motion can be edited, reviewed and replaced alone;
+ * `main.scss` loads them and is the file to compile. The theme's CSS is the
+ * same as `specToScss()`'s.
+ *
+ * Every setting has its place, written out even when the theme leaves it
+ * alone: each token group's file and the type system's list every default,
+ * commented, so a change is an uncomment; `_settings.scss` holds the
+ * breakpoints, and builds greese ui's stylesheet and utility classes with them
+ * whenever they differ from the library's.
+ *
+ *   main.scss              the entry: only `@use` lines
+ *   _settings.scss         breakpoints, `$library`, `$utilities` and `$theme`
+ *   _library.scss          greese ui's stylesheet, built here when `$library`
+ *   _resets.scss           theme layers taken back from components, first
+ *   tokens/_index.scss     one `tokens()` call per group, then the type system
+ *   tokens/_<group>.scss   a group's values (`$tokens`) and new tokens (`$extend`)
+ *   tokens/_typography.scss
+ *   motion/_index.scss     effects, motion roles and page transitions
+ *   components/_<name>.scss   one component each, its own imports and helpers
+ *   shapes/_index.scss     the shapes, their sizes and what takes them
+ *   utilities/_index.scss  greese ui's utility classes when `$utilities`, and yours
+ *
+ * `options.components` names component modules of your own
+ * (`components/_hero.scss`) for `main.scss` to load too, so a tool that
+ * rewrites the layout keeps loading the files it no longer writes.
+ */
+export declare const specToLayout: (spec: ThemeSpec, source?: string, options?: {
+    components?: string[];
+}) => Record<string, string>;