@webround/core 0.1.8 → 0.3.0

package/dist/style.d.ts

@@ -0,0 +1,456 @@
+export interface WrBreakpoint {
+    id: 'base' | 'mobile' | 'sm' | 'md' | 'lg' | 'xl';
+    /** The Tailwind prefix (`md:`); none for base. */
+    variant: string;
+    /** From this width (px) up; base is every screen. */
+    minWidth: number;
+    label: string;
+    description: string;
+}
+/** Mobile first: a value at a breakpoint holds from that width up, until a wider breakpoint says otherwise. */
+export declare const WR_BREAKPOINTS: readonly WrBreakpoint[];
+export type WrBreakpointId = WrBreakpoint['id'];
+export declare const WR_BREAKPOINT_IDS: ("base" | "sm" | "mobile" | "md" | "lg" | "xl")[];
+/**
+ * What a breakpoint inherits from, own first: mobile first, so a width counts the narrower ones (md: base, sm, md). Mobile is the exception: it holds BELOW md (`max-md:`), so it only
+ * has the base to fall back on, and no other width counts it.
+ */
+export declare function wrStyleCascade(breakpoint: WrBreakpointId): WrBreakpointId[];
+export type WrStyleGroup = 'spacing' | 'size' | 'text' | 'color' | 'border' | 'effects' | 'motion' | 'layout';
+export declare const WR_STYLE_GROUPS: Record<WrStyleGroup, string>;
+/**
+ * A state an element can be in, and what it looks like then: a value of a property that can change with it is written with the state's variant (`hover:bg-accent`; at a breakpoint
+ * `md:hover:bg-accent`). Only some properties can (see `WrStyleProperty.states`): the ones that make sense to change while the pointer is over it, or it has the keyboard's focus.
+ */
+export interface WrState {
+    id: 'hover' | 'focus' | 'active';
+    /** The Tailwind variant. */
+    variant: string;
+    label: string;
+    description: string;
+}
+export declare const WR_STATES: readonly WrState[];
+export type WrStateId = WrState['id'];
+export declare const WR_STATE_IDS: readonly WrStateId[];
+/** One value a property can have: its name, the class that says it, and what it means in CSS. */
+export interface WrStyleValue {
+    /** What it is called everywhere (a number of the scale, a token, an option): this is what is read and written. */
+    value: string;
+    /** The Tailwind class, without the breakpoint (`px-4`). */
+    class: string;
+    label: string;
+    /** What it comes to, in CSS terms (`1rem (16px)`). */
+    css?: string;
+    /** For a color: how it looks (a CSS color), when the project's stylesheet says it. */
+    swatch?: string;
+}
+export interface WrStyleProperty {
+    id: string;
+    label: string;
+    /** One sentence, in plain words. */
+    description: string;
+    group: WrStyleGroup;
+    /** How the control looks: a step of a scale, a color of the theme, one of a few options. */
+    control: 'scale' | 'color' | 'options';
+    values: readonly WrStyleValue[];
+    /** The properties that are parts of this one: setting this replaces them (padding replaces padding-x, padding-top…). */
+    includes?: readonly string[];
+    /** Prefix of the classes that mean a value outside the table (`w-[320px]`): read and replaced, never written. */
+    customPrefix?: string;
+    /** Values that are not in `values` but that Tailwind writes all the same (`px-27`): the numbers of the scale, whole pixels, fractions. */
+    free?: WrStyleFree;
+    /** The multi-side model this property is a part of (padding, margin, gap): the panel shows it through the model, not as a row of its own. */
+    compound?: string;
+    /** It can be set for a state too (hover, focus, pressed). */
+    states?: true;
+    /** A color: the class prefix of one picked on the fly (`bg` makes `bg-[#22c55e]`), outside the theme's. */
+    hex?: string;
+    /** The values people reach for most (ids of `values`), in the order to offer them: what a quick control puts a click away. */
+    shortcuts?: readonly string[];
+    /** Variants every class of it carries after the screen and the state (`motion-safe` for an animation: it does not run for who asked their system for less motion). */
+    variants?: readonly string[];
+}
+/**
+ * A property that takes any number, not only the ones of the list (Tailwind 4 writes `px-27`, `w-3/7`, `border-3` on demand): what is accepted, and what it comes to.
+ * `values` keeps the useful ones (the steps people use, the keywords) as suggestions.
+ */
+export interface WrStyleFree {
+    /** `step`: any number of the spacing scale, a step being a quarter of a rem (`px-27` is 6.75rem, 108px; `p-1.25`); `integer`: a whole number of pixels (`border-3`). */
+    kind: 'step' | 'integer';
+    /** The class prefix: `px` in `px-27`. */
+    prefix: string;
+    max: number;
+    /** A negative number too (`-mt-4`). */
+    negative?: boolean;
+    /** A fraction of the parent too (`w-3/7`). */
+    fractions?: boolean;
+}
+export interface WrStyleOptions {
+    /** The colors the project's theme names (`accent`, `fg`…); the default ones when not given. */
+    colorTokens?: readonly string[];
+    /** How each of them looks (a CSS color), for the ones the stylesheet says. */
+    colorSwatches?: Readonly<Record<string, string>>;
+}
+/** The semantic colors of the starter site's theme (index.css `@theme`): the project's own list replaces it (see `WrStyleOptions`). */
+export declare const WR_DEFAULT_COLOR_TOKENS: readonly string[];
+/** What a value of a property is: one of its list, or (when the property is free) any number it accepts. null when it is neither. */
+export declare function wrStyleParseValue(property: {
+    values: readonly WrStyleValue[];
+    free?: WrStyleFree;
+    hex?: string | true;
+}, text: string): WrStyleValue | null;
+/** What a free property accepts, in words: for the field that takes it and for an error that refuses it. */
+export declare function wrStyleFreeHint(free: WrStyleFree): string;
+/**
+ * The entry animations (fade in, slide up, zoom in) are not Tailwind's own: they need their keyframes in the theme (`--animate-*` in an `@theme`, which Tailwind 4 turns into the class
+ * `animate-fade-in`). This is the ONE text of them: the operations write it into `theme.css` the first time one is used, and the tests compile it. The three built in (pulse, bounce, spin,
+ * ping) need nothing.
+ */
+export declare const WR_ENTRY_ANIMATIONS: readonly string[];
+export declare const WR_ENTRY_ANIMATIONS_CSS: Readonly<Record<string, {
+    value: string;
+    keyframes: string;
+}>>;
+/** Every property the panel, the operations and the API speak of, in the order they are shown. */
+export declare function wrStyleProperties(options?: WrStyleOptions): readonly WrStyleProperty[];
+export interface WrClassToken {
+    raw: string;
+    /** `['md', 'hover']` for `md:hover:underline`. */
+    variants: string[];
+    /** What is left: `underline`, `-mt-4`, `!p-4`, `w-[calc(100%-2rem)]`. */
+    utility: string;
+}
+/** Splits a className into its classes; a `:` inside `[…]` is part of a value (`bg-[url(http://x)]`), not a variant. */
+export declare function wrParseClassName(className: string): WrClassToken[];
+export interface WrStyleEntry {
+    property: string;
+    breakpoint: WrBreakpointId;
+    /** The value of the table; null when the class is outside it (see `custom`). */
+    value: string | null;
+    /** The class as it is written in the code, breakpoint included (`md:px-6`). */
+    class: string;
+    /** The class is a value the table does not offer (`w-[320px]`, `p-13`): it is kept as it is until the property is set again at that breakpoint. */
+    custom?: true;
+    /** The state it holds in (hover, focus, pressed); none: always. */
+    state?: WrStateId;
+}
+/**
+ * Everything a className says about the properties of the table, at the breakpoints it names. Several classes for one property: the last one is what is read. `state`: what it says for that
+ * state (`hover:bg-accent`); without it, only what holds always (the classes of a state are not mixed in).
+ */
+export declare function wrStyleRead(className: string, options?: WrStyleOptions, state?: WrStateId): WrStyleEntry[];
+/** The classes the table does not read: `dark:` and other variants (what the table reads of `hover:`, `focus:` and `active:` is the state of a property that can have one), `!important`, what is not about a property of the table, the project's own classes. They are never touched. */
+export declare function wrStyleUnmanaged(className: string, options?: WrStyleOptions): string[];
+/** What a property is at a breakpoint once the narrower screens are counted: its own value, or the nearest smaller breakpoint's. */
+export declare function wrStyleEffective(entries: readonly WrStyleEntry[], property: string, breakpoint: WrBreakpointId): {
+    value: string | null;
+    from: WrBreakpointId;
+    custom?: true;
+} | null;
+export interface WrStyleChange {
+    property: string;
+    breakpoint: WrBreakpointId;
+    /** A value of the property (see `wrStyleProperties`), or null to take it away at that breakpoint. */
+    value: string | null;
+    /** The state it is for (hover, focus, pressed); none: always. Only the properties that can have one (`WrStyleProperty.states`). */
+    state?: WrStateId;
+}
+export type WrStyleErrorCode = 'unknown-property' | 'unknown-breakpoint' | 'invalid-value' | 'unknown-state' | 'invalid-state';
+export declare class WrStyleError extends Error {
+    readonly code: WrStyleErrorCode;
+    constructor(code: WrStyleErrorCode, message: string);
+}
+/** The className once every change is made, in order. A value that is not the property's, a property or a breakpoint that does not exist: a `WrStyleError` that says what there is. */
+export declare function wrStyleApply(className: string, changes: readonly WrStyleChange[], options?: WrStyleOptions): string;
+/**
+ * The classes of one screen put on another (`to` a breakpoint), or on every screen at once (`to: 'all'`). The classes are copied as they are written, so what the table does not offer
+ * (`w-[320px]`) goes too; only the style classes move: hover:, dark: and the project's own stay where they are.
+ *  - to a breakpoint: for each property `from` says, `to` says the same; the same properties are replaced (a wider one takes out the narrower it includes: p replaces px), the rest of
+ *    `to` stays. What `from` inherits from narrower screens is not copied: it is not written there.
+ *  - to 'all': one clean list. The look `from` has once the narrower screens are counted becomes what every screen has; every class of another breakpoint is taken away. From "All screens"
+ *    that is only taking the overrides away.
+ * `only`: just these properties (and the ones they include or are included by: padding and padding-x say the same thing); every other class stays as it is. `state`: the classes of that state
+ * (hover…) and no others; without it, the ones that hold always. Pure; an unknown breakpoint or state is a `WrStyleError`.
+ */
+export declare function wrStyleCopyTo(className: string, from: WrBreakpointId, to: WrBreakpointId | 'all', options?: WrStyleOptions, only?: readonly string[], state?: WrStateId): string;
+/**
+ * Makes changes hold on every screen: each is made at the breakpoint it names, and then what the element looks like there, for those properties only, becomes what every screen has (the
+ * overrides of the other screens for them are taken away). A change that takes a value away (`null`) takes it away from every screen. What the changes do not touch keeps its overrides.
+ * This is what "All screens" does in the editor: you set it where you are looking, and it holds everywhere. Pure.
+ */
+export declare function wrStyleApplyEverywhere(className: string, changes: readonly WrStyleChange[], options?: WrStyleOptions): string;
+/**
+ * Two groups of classes put together, `over` winning where both say something: what an element looks like when a shared style (`under`) is written out on it and the element has classes
+ * of its own (`over`). A class of `under` is left out when `over` says the same property at the same breakpoint, or a wider property that includes it there (p over px); everything else
+ * of `under` stays, then all of `over`. Pure.
+ */
+export declare function wrStyleLayer(under: string, over: string, options?: WrStyleOptions): string;
+/** A style entry in words: what a person reads in the panel and an AI or a tool reads in an answer. */
+export interface WrStyleDescription {
+    property: string;
+    propertyLabel: string;
+    breakpoint: WrBreakpointId;
+    breakpointLabel: string;
+    value: string | null;
+    valueLabel: string;
+    css?: string;
+    class: string;
+    custom?: true;
+    /** The state it is for (hover…), and its name. */
+    state?: WrStateId;
+    stateLabel?: string;
+    sentence: string;
+}
+export declare function wrStyleDescribe(entries: readonly WrStyleEntry[], options?: WrStyleOptions): WrStyleDescription[];
+/** How finely a multi-side property is said: one value for all, one per pair, one for each side. */
+export type WrStyleSidesMode = 'all' | 'axis' | 'sides';
+export interface WrStyleCompoundPart {
+    property: string;
+    label: string;
+    /** The finest parts this one says at once (the whole, a pair, or just itself): what makes a switch from a mode to another lossless or not. */
+    covers: string[];
+}
+export interface WrStyleCompoundMode {
+    id: WrStyleSidesMode;
+    label: string;
+    description: string;
+    parts: WrStyleCompoundPart[];
+}
+/**
+ * A property that is said by sides (padding, margin) or by axes (gap): the panel shows it through ONE model with a mode, instead of one row per property:
+ * all at once, a pair at a time (top and bottom, left and right), or each one by itself. The modes, which properties each is made of and what each covers are
+ * written here, once.
+ */
+export interface WrStyleCompound {
+    id: string;
+    label: string;
+    description: string;
+    group: WrStyleGroup;
+    modes: WrStyleCompoundMode[];
+}
+export declare const WR_STYLE_COMPOUNDS: readonly WrStyleCompound[];
+type Own = Pick<WrStyleEntry, 'property' | 'breakpoint' | 'value'> & {
+    custom?: true;
+};
+/** The mode that shows what an element has at a breakpoint: the finest one with something set in it (the panel opens there). */
+export declare function wrStyleCompoundMode(compound: WrStyleCompound, entries: readonly Own[], breakpoint: WrBreakpointId): WrStyleSidesMode;
+export interface WrStyleCompoundValue {
+    /** What the part comes to (null: nothing sets it). */
+    value: string | null;
+    /** The part has a value of its own at this breakpoint (a cross can take it away); otherwise it is what a coarser part, or a narrower screen, says. */
+    own: boolean;
+    /** Where it comes from: this breakpoint, or the nearest narrower one that says something. */
+    from: WrBreakpointId;
+    /** The part joins sides that come to different values (it cannot be said as one). */
+    mixed: boolean;
+}
+/**
+ * What a part of a multi-side model comes to at a breakpoint once everything that says something about it is counted: its own value, the coarser part that covers it (`padding`
+ * for `padding-top`), and the narrower screens (mobile first). So in "each side" mode a side that has no class of its own shows what the whole says.
+ */
+export declare function wrStyleCompoundValue(compound: WrStyleCompound, entries: readonly Own[], breakpoint: WrBreakpointId, part: WrStyleCompoundPart): WrStyleCompoundValue;
+export type WrStyleSwitch = {
+    ok: true;
+    changes: WrStyleChange[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * What changing the mode of a multi-side property asks for, so that the element looks the same: going to a finer mode copies the value to the parts (and takes the
+ * coarser ones away); going to a coarser one needs the parts it joins to agree (to be the same value, or all none), and says why when they do not. A value outside the table
+ * (`px-[3px]`) cannot be copied: it is said, not lost.
+ */
+export declare function wrStyleCompoundSwitch(compound: WrStyleCompound, entries: readonly Own[], breakpoint: WrBreakpointId, to: WrStyleSidesMode): WrStyleSwitch;
+/** Everything there is to say, as plain data: what `style-catalog` answers, and what the editor's panel is drawn from. */
+export interface WrStyleCatalog {
+    breakpoints: {
+        id: WrBreakpointId;
+        label: string;
+        description: string;
+        minWidth: number;
+    }[];
+    note: string;
+    groups: Record<WrStyleGroup, string>;
+    /** The states a property that can have one can be set for. */
+    states: {
+        id: WrStateId;
+        label: string;
+        description: string;
+    }[];
+    colorTokens: string[];
+    properties: {
+        id: string;
+        label: string;
+        description: string;
+        group: WrStyleGroup;
+        control: WrStyleProperty['control'];
+        includes?: string[];
+        includesNote?: string;
+        /** Any number is accepted too (and what a number is): see `WrStyleFree`. The field takes it; `hint` says it in words. */
+        free?: WrStyleFree & {
+            hint: string;
+        };
+        /** The multi-side model it is a part of. */
+        compound?: string;
+        /** It can be set for a state (hover, focus, pressed) too. */
+        states?: true;
+        /** A color can also be picked on the fly (a hex color), outside the theme's. */
+        hex?: true;
+        /** The values people reach for most, in the order to offer them. */
+        shortcuts?: string[];
+        values: {
+            value: string;
+            label: string;
+            css?: string;
+            class: string;
+            swatch?: string;
+        }[];
+    }[];
+    compounds: WrStyleCompound[];
+}
+export declare function wrStyleCatalog(options?: WrStyleOptions): WrStyleCatalog;
+/** Whether the panel offers a control for this kind of element (`text`, `section`, `image`…). `item` is a property id, or a model's (`padding`). */
+export declare function wrStyleOffered(item: string, kind: string | undefined): boolean;
+/** An edge of an element that can be dragged to change a property: the right one for the width, the bottom one for the height. */
+export interface WrStyleHandle {
+    property: 'width' | 'height';
+    edge: 'right' | 'bottom';
+    /** What the handle is for, in words (its accessible name). */
+    label: string;
+}
+export declare const wrStyleHandles: (kind: string | undefined) => readonly WrStyleHandle[];
+/**
+ * What the quick bar on the selected element offers. The few things people do most, and which of them make sense for the kind of element: a box has its size, its room around and inside,
+ * the gap between its children, a background and where they sit; an image has a size and a margin; a text written in the editor has its own toolbar, so only its size and margin. The
+ * panel is for the rest. One table: what the bar shows for a component is said here and nowhere else.
+ */
+export type WrQuickItem = 'width' | 'height' | 'padding' | 'margin' | 'gap' | 'background-color' | 'align' | 'duplicate' | 'delete';
+export declare const wrStyleQuick: (kind: string | undefined) => readonly WrQuickItem[];
+/** A side of an element's padding or margin that can be dragged on the page. */
+export interface WrStyleSpaceHandle {
+    /** The property a drag writes (`padding-top`). */
+    property: 'padding-top' | 'padding-right' | 'padding-bottom' | 'padding-left' | 'margin-top' | 'margin-right' | 'margin-bottom' | 'margin-left';
+    kind: 'padding' | 'margin';
+    side: 'top' | 'right' | 'bottom' | 'left';
+    /** The property that says all four sides at once (what Shift writes). */
+    all: 'padding' | 'margin';
+    /** What it is, in words (its accessible name). */
+    label: string;
+}
+export declare const wrStyleSpaceHandles: (kind: string | undefined) => readonly WrStyleSpaceHandle[];
+export interface WrStyleSpaceResult {
+    /** What `style-set` takes (`4`). */
+    value: string;
+    class: string;
+    /** For the person: `pt-4 · 16px`. */
+    label: string;
+    /** The CSS that shows it now, before it is written (`1rem`). */
+    css: string;
+    px: number;
+}
+/**
+ * What a padding or a margin dragged to `px` comes to: a whole step of the spacing scale (a quarter of a rem, 4px: nothing finer is asked of a hand), never negative (a drag does not make a
+ * negative margin). `property` is the side (`padding-top`) or all of them (`padding`). null for a property that is not one of these. Pure, like `wrStyleDrag`.
+ */
+export declare function wrStyleSpaceDrag(property: string, px: number, rem?: number): WrStyleSpaceResult | null;
+export interface WrStyleDragContext {
+    /** The width the parent leaves for the element, in px: the width snaps to a fraction of it (`1/2`, `3/4`) or all of it (`full`) when it comes close. */
+    parent?: number;
+    /** The size of 1rem in px (16 unless the site says otherwise). */
+    rem?: number;
+    /** Whether a width snaps to a fraction of the parent (true unless it is false): a hand wants it, an arrow key that moves one step at a time does not (it would never leave the fraction). */
+    fractions?: boolean;
+    /** The smallest the element can be where it is, in px (what the page measured): a size under it is a size the page would not show, so it is not offered. */
+    floor?: number;
+}
+/** The smallest step number (`w-N`) that is not under `floor` px: the number a field takes as its minimum. 0 when there is no floor. */
+export declare const wrStyleFloorStep: (floor: number | undefined, rem?: number) => number;
+export interface WrStyleDragResult {
+    /** What `style-set` takes (`64`, `3/4`, `full`). */
+    value: string;
+    class: string;
+    /** For the person: `w-64 · 256px`. */
+    label: string;
+    /** The CSS that shows it now, before it is written (`16rem`, `75%`). */
+    css: string;
+    px: number;
+}
+/**
+ * What a size dragged to `px` comes to: a whole step of the spacing scale (a quarter of a rem, 4px: nothing finer is asked of a hand), or, for a width, a fraction of the parent when
+ * it comes close to one. null for a property that is not a size. Pure, so the same answer is given for the person dragging and for a test.
+ */
+export declare function wrStyleDrag(property: 'width' | 'height', px: number, context?: WrStyleDragContext): WrStyleDragResult | null;
+/** Where the children of a box sit along an axis. */
+export type WrStyleAlignSide = 'start' | 'center' | 'end';
+export declare const WR_STYLE_ALIGN_SIDES: readonly WrStyleAlignSide[];
+/** The kinds of element whose children can be aligned like this: the boxes (a text, a button, an image have no children to place). */
+export declare const wrStyleCanAlign: (kind: string | undefined) => boolean;
+export type WrStyleAlignment = {
+    ok: true;
+    horizontal: WrStyleAlignSide | null;
+    vertical: WrStyleAlignSide | null; /** There is no height: a vertical alignment has no room to move in. */
+    needsHeight: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Where the children sit now (the cell of the grid that is on), or why this box cannot be aligned. */
+export declare function wrStyleAlignRead(entries: readonly Own[], breakpoint: WrBreakpointId): WrStyleAlignment;
+/**
+ * What to write to put the children at a place of the grid (horizontal × vertical), ALL at once: the layout that makes it work (a plain box becomes a flex column: its
+ * children stack as before) and both alignments, whichever axis each is on. Written separately these pieces do nothing (`items-center` on a block box does not move anything), which
+ * is why they are one change.
+ */
+export declare function wrStyleAlignSet(entries: readonly Own[], breakpoint: WrBreakpointId, horizontal: WrStyleAlignSide, vertical: WrStyleAlignSide): {
+    ok: true;
+    changes: WrStyleChange[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** What to write to take the alignment away at a breakpoint (the box stays as it is laid out). */
+export declare const wrStyleAlignClear: (breakpoint: WrBreakpointId) => WrStyleChange[];
+/** A way a box lays its children out: a column, a row, columns, a grid. */
+export interface WrStyleLayout {
+    id: string;
+    label: string;
+    description: string;
+    /** What it is made of: the layout properties it sets, at each screen width (all responsive: columns become one on a phone). */
+    recipe: readonly {
+        property: string;
+        breakpoint: WrBreakpointId;
+        value: string;
+    }[];
+    /** The gap it gives the box when it has none. */
+    gap: string | null;
+}
+/** The layouts, in the order they are offered: the one table that the panel, the quick menu, the API and the tools read. */
+export declare const WR_STYLE_LAYOUTS: readonly WrStyleLayout[];
+/** The kinds of element that can change layout: the boxes (they hold other elements). */
+export declare const wrStyleCanLayout: (kind: string | undefined) => boolean;
+/**
+ * Which layout a box has: the id of the one it matches exactly (only its layout properties count, not the gap or the alignment), `null` when it has none of those set, `'custom'`
+ * when it has something that is none of the layouts.
+ */
+export declare function wrStyleLayoutRead(entries: readonly Own[]): string | 'custom' | null;
+/**
+ * What to write to turn a box into a layout, ALL at once and at every screen width: what the old layout set is taken away (a row's `md:flex-row` must not survive into columns), the
+ * new one is written, and a gap is given if the box had none (columns glued together are not columns). One change list: one undo.
+ */
+export declare function wrStyleLayoutSet(entries: readonly Own[], layoutId: string): {
+    ok: true;
+    changes: WrStyleChange[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Every CSS property a preview may touch: what a page is asked to show is limited to these, whatever is asked. */
+export declare const WR_STYLE_PREVIEW_CSS: ReadonlySet<string>;
+/**
+ * The CSS that shows a value of a number property now (`padding-top` at 6 is `padding-top: 1.5rem`), for a page to wear while the value is dragged: nothing is written, and the
+ * page gives it back. null when it cannot be shown that way (the value is written without a preview). The same table as the classes: a step is a quarter of a rem.
+ */
+export declare function wrStylePreviewCss(property: string, value: string): Record<string, string> | null;
+export {};
+//# sourceMappingURL=style.d.ts.map