@nexxtmove/ui 2.2.0 → 2.3.0

package/dist/components/organisms/ColorPicker/gradient.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The gradient of NexxtColorPicker's gradient mode, as plain data. The picker
+ * knows no class names: a wrapper such as NexxtEditorColor turns this into
+ * whatever it stores.
+ */
+/** A named colour a stop can be bound to, such as a theme role. Always opaque. */
+export interface ColorPickerPreset {
+    /** What the wrapper knows the preset by, such as `'main'`. */
+    key: string;
+    /** Name of the preset as the user reads it, announced on the stop's handle. */
+    label: string;
+}
+export interface ColorPickerGradientStop {
+    /** The colour as `#rrggbb`, or `#rrggbbaa` below full opacity; lower case. */
+    color: string;
+    /** Whole percentage, 0–100. */
+    position: number;
+    /** Set when the stop is bound to a preset; `color` is then the preset's hex. */
+    preset?: ColorPickerPreset;
+}
+export interface ColorPickerGradient {
+    type: 'linear' | 'radial';
+    /** Whole degrees, 0–359, clockwise from the top. Only used by a linear gradient. */
+    angle: number;
+    /** Centre in whole percentages from the left. Only used by a radial gradient. */
+    centerX: number;
+    /** Centre in whole percentages from the top. Only used by a radial gradient. */
+    centerY: number;
+    /** Two or three stops, in order of position. */
+    stops: ColorPickerGradientStop[];
+}
+export declare const MIN_STOPS = 2;
+export declare const MAX_STOPS = 3;
+export declare const DEFAULT_ANGLE = 180;
+export declare const DEFAULT_CENTER = 50;
+/** What the gradient mode shows while there is no readable gradient. */
+export declare const DEFAULT_GRADIENT: ColorPickerGradient;
+/** Rounds and clamps to a whole percentage. */
+export declare const clampPercent: (value: number) => number;
+/** Rounds and wraps to a whole angle, 0–359: 360 is 0 and -10 is 350. */
+export declare const wrapAngle: (value: number) => number;
+/** A stop as CSS needs it: any CSS colour, and a position in percent. */
+export interface CssGradientStop {
+    color: string;
+    position: number;
+}
+/** The shape of a gradient as CSS needs it. */
+export type CssGradientShape = {
+    type: 'linear';
+    angle: number;
+} | {
+    type: 'radial';
+    centerX: number;
+    centerY: number;
+};
+/**
+ * A gradient as a CSS `background-image`, always interpolated in oklab and with
+ * every position written. This is how the consuming app draws a gradient class
+ * (as inline CSS), so the preview shows exactly what the app renders. For
+ * `bg-linear-*` and `bg-radial` it is also what the Tailwind class renders;
+ * for `bg-radial-[at_…]` Tailwind would interpolate in sRGB, the app does not.
+ * The position comes before the interpolation method, as in
+ * `radial-gradient(at 30% 70% in oklab, …)`; a centred radial gradient leaves
+ * the position out.
+ */
+export declare const buildGradientCss: (shape: CssGradientShape, stops: CssGradientStop[]) => string;
+/** The picker's gradient as CSS; see `buildGradientCss`. */
+export declare const gradientCss: (gradient: ColorPickerGradient) => string;
+/** The stops left to right in oklab, for the stop bar. */
+export declare const stopBarCss: (gradient: ColorPickerGradient) => string;
+/** The checkerboard that shows through a translucent colour. */
+export declare const CHECKERBOARD = "repeating-conic-gradient(#e5e7eb 0% 25%, #ffffff 0% 50%)";
+type Rgba = [r: number, g: number, b: number, a: number];
+/** `#rrggbb`, or `#rrggbbaa` below full opacity, in lower case. */
+export declare const formatHex: ([r, g, b, a]: Rgba) => string;
+/** A hex in the one spelling the picker reports: lower case, without an opaque `ff`. */
+export declare const normalizeHex: (hex: string) => string;
+/**
+ * Mixes two colours the way a CSS gradient does: in the given space, with
+ * premultiplied alpha, so a fade from a transparent black to a colour keeps the
+ * colour's hue all the way.
+ */
+export declare const mixColors: (from: string, to: string, t: number, space: "oklab" | "srgb") => string;
+/**
+ * The colour the gradient shows at `position`, as a hex: what a stop added
+ * there needs so that the gradient does not change. Interpolated in oklab, as
+ * every gradient is drawn. Before the first stop and after the last the
+ * gradient is flat.
+ */
+export declare const colorAt: (stops: ColorPickerGradientStop[], position: number) => string;
+/**
+ * Copy of the gradient mode. Every key is optional and merged over the Dutch
+ * defaults. `{n}`, `{total}`, `{x}` and `{y}` are filled in by the picker.
+ */
+export interface ColorPickerGradientMessages {
+    /** Accessible name of the solid/gradient switch. Defaults to `'Vulling'`. */
+    mode?: string;
+    /** Solid option of the switch. Defaults to `'Effen'`. */
+    solid?: string;
+    /** Gradient option of the switch. Defaults to `'Verloop'`. */
+    gradient?: string;
+    /** Accessible name of the type switch. Defaults to `'Type verloop'`. */
+    type?: string;
+    /** Linear option of the type switch. Defaults to `'Lineair'`. */
+    linear?: string;
+    /** Radial option of the type switch. Defaults to `'Radiaal'`. */
+    radial?: string;
+    /** Accessible name of the angle point in the preview. Defaults to `'Hoek'`. */
+    angle?: string;
+    /** Value text of the angle point. Defaults to `'{n} graden'`. */
+    angleValue?: string;
+    /** Accessible name of the centre point in the preview. Defaults to `'Middelpunt'`. */
+    center?: string;
+    /** Value text of the centre point. Defaults to `'{x} % van links, {y} % van boven'`. */
+    centerValue?: string;
+    /** Accessible name of the reverse button. Defaults to `'Kleurstops omdraaien'`. */
+    reverse?: string;
+    /** Heading above the stop list. Defaults to `'Kleurstops'`. */
+    stops?: string;
+    /** Hint next to the heading. Defaults to `'max. 3'`. */
+    max?: string;
+    /** Why no stop can be added, announced on the add button. Defaults to `'Een verloop heeft maximaal 3 kleurstops.'`. */
+    maxReason?: string;
+    /** Visible text of the add button. Defaults to `'Toevoegen'`. */
+    add?: string;
+    /** Accessible name of the add button. Defaults to `'Kleurstop toevoegen'`. */
+    addName?: string;
+    /** Name of a stop's row and of its handle on the bar. Defaults to `'Kleurstop {n} van {total}'`. */
+    stop?: string;
+    /** Accessible name of a row's position field. Defaults to `'Positie (%)'`. */
+    position?: string;
+    /** Accessible name of a row's colour button. Defaults to `'Kleur kiezen'`. */
+    pick?: string;
+    /** Accessible name of a row's hex field. Defaults to `'Hex'`. */
+    hex?: string;
+    /** Accessible name of a row's remove button. Defaults to `'Verwijderen'`. */
+    remove?: string;
+    /** Accessible name of a stop's colour popover. Defaults to `'Kleur van kleurstop {n}'`. */
+    dialog?: string;
+    /** Opacity part of a handle's value text. Defaults to `'dekking {n} %'`. */
+    stopOpacity?: string;
+    /** Hint under the locked opacity slider of a stop bound to a preset. Defaults to `'Huisstijlkleuren zijn altijd dekkend.'`. */
+    roleOpaque?: string;
+    /** Trigger text for a linear gradient. Defaults to `'Lineair verloop'`. */
+    triggerLinear?: string;
+    /** Trigger text for a radial gradient. Defaults to `'Radiaal verloop'`. */
+    triggerRadial?: string;
+    /** Name of the trigger swatch for a linear gradient. Defaults to `'Geselecteerd verloop: lineair, {n} kleuren'`. */
+    swatchLinear?: string;
+    /** Name of the trigger swatch for a radial gradient. Defaults to `'Geselecteerd verloop: radiaal, {n} kleuren'`. */
+    swatchRadial?: string;
+    /** Name of the trigger swatch while there is no gradient. Defaults to `'Geen kleur geselecteerd'`. */
+    swatchEmpty?: string;
+}
+export declare const DEFAULT_GRADIENT_MESSAGES: {
+    mode: string;
+    solid: string;
+    gradient: string;
+    type: string;
+    linear: string;
+    radial: string;
+    angle: string;
+    angleValue: string;
+    center: string;
+    centerValue: string;
+    reverse: string;
+    stops: string;
+    max: string;
+    maxReason: string;
+    add: string;
+    addName: string;
+    stop: string;
+    position: string;
+    pick: string;
+    hex: string;
+    remove: string;
+    dialog: string;
+    stopOpacity: string;
+    roleOpaque: string;
+    triggerLinear: string;
+    triggerRadial: string;
+    swatchLinear: string;
+    swatchRadial: string;
+    swatchEmpty: string;
+};
+export type GradientCopy = typeof DEFAULT_GRADIENT_MESSAGES;
+/** Fills `{key}` placeholders in a message. */
+export declare const fillMessage: (message: string, values: Record<string, string | number>) => string;
+export {};

package/dist/components/organisms/ColorPicker/gradientGeometry.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Geometry of the gradient preview: where a stop renders in a square of side
+ * `S`, and which angle, centre and positions a set of points stands for. The
+ * square's origin is its top-left corner with y pointing down; its centre is
+ * C = (S/2, S/2). Every derivation works on the rounded values that are
+ * written to the model, so the points and the rendered gradient always agree.
+ *
+ * Linear (CSS: 0° is up, clockwise): direction d = (sin θ, −cos θ), length of
+ * the gradient line L = S·(|sin θ| + |cos θ|), and a point P sits at
+ * t = 0.5 + ((P − C)·d) / L.
+ *
+ * Radial (`ellipse farthest-corner`): an ellipse with the proportions of
+ * `closest-side` that runs through the farthest corner, and t is the
+ * normalized distance from the centre.
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+export declare const linearDirection: (angle: number) => Point;
+/** Length of the CSS gradient line for `angle` in a square of side `size`. */
+export declare const linearLength: (angle: number, size: number) => number;
+/** Where on the gradient line a point projects, 0–1 inside the square (unclamped). */
+export declare const linearT: (angle: number, point: Point, size: number) => number;
+/** The position a point stands for: a whole percentage, 0–100. */
+export declare const linearPosition: (angle: number, point: Point, size: number) => number;
+/** The canonical point of a position: on the line through the middle. */
+export declare const linearPoint: (angle: number, position: number, size: number) => Point;
+/** Whether a point lies in the square (edges included). */
+export declare const isInSquare: (point: Point, size: number) => boolean;
+/** A pointer clamped onto the square, so a dragged point never leaves it. */
+export declare const clampToSquare: (point: Point, size: number) => Point;
+/**
+ * Where the handle of a position is drawn: its canonical point, or -- when that
+ * lies outside the square, as 0 % and 100 % do at angles off the axes -- where
+ * the gradient line leaves the square. The handle is a grip; the class and the
+ * numbers stay the real CSS values.
+ */
+export declare const linearHandlePoint: (angle: number, position: number, size: number) => Point;
+/**
+ * The angle from the from-point to the to-point, in whole degrees 0–359. Two
+ * points closer than `minDistance` say nothing about a direction, so the
+ * previous angle stays.
+ */
+export declare const angleBetween: (from: Point, to: Point, previous: number, minDistance: number) => number;
+/** How far a point lies along the segment from `a` to `b`, clamped to 0–1. */
+export declare const projectOnSegment: (point: Point, a: Point, b: Point) => number;
+/** The point at fraction `f` from `a` to `b`. */
+export declare const lerpPoint: (a: Point, b: Point, f: number) => Point;
+/** Where the via stop sits between from and to: (via − from) / (to − from), or 0.5. */
+export declare const viaFraction: (from: number, via: number, to: number) => number;
+/**
+ * The angle and positions a set of points stands for: the angle from the
+ * from-point to the to-point, each position the projection of its point on the
+ * line of that rounded angle, and via at fraction `f` of the segment.
+ */
+export declare const linearFromPoints: (options: {
+    from: Point;
+    to: Point;
+    viaFraction?: number;
+    previousAngle: number;
+    size: number;
+    minDistance: number;
+}) => {
+    angle: number;
+    from: number;
+    via: number | undefined;
+    to: number;
+};
+export interface RadialEllipse {
+    /** Centre in px. */
+    x: number;
+    y: number;
+    /** Radii in px. */
+    rx: number;
+    ry: number;
+}
+/**
+ * Clamps a centre percentage to 1–99: at 0 or 100 the closest side is 0 and
+ * CSS degenerates the ellipse.
+ */
+export declare const clampCenter: (value: number) => number;
+/** The `farthest-corner` ellipse of a centre at (cx %, cy %) in a square of side `size`. */
+export declare const radialEllipse: (cx: number, cy: number, size: number) => RadialEllipse;
+/** The normalized distance of a point from the centre; 1 on the ellipse (unclamped). */
+export declare const radialT: (ellipse: RadialEllipse, point: Point) => number;
+export declare const radialPosition: (ellipse: RadialEllipse, point: Point) => number;
+/** The direction of the ray through a point, in the ellipse's own coordinates. */
+export declare const radialAngle: (ellipse: RadialEllipse, point: Point) => number;
+/** The ray towards the farthest corner, where 100 % falls exactly on the corner. */
+export declare const farthestCornerAngle: (ellipse: RadialEllipse, size: number) => number;
+/**
+ * The ray the stops are drawn on: `psi` while the farthest stop (`position`)
+ * still lies inside the square, otherwise the ray to the farthest corner. That
+ * one always fits: 100 % lands exactly on the corner. A ψ from a drag, or one
+ * left over after the centre moved, could otherwise put a point outside the
+ * preview, over the controls around it.
+ */
+export declare const radialRay: (ellipse: RadialEllipse, psi: number | null, position: number, size: number) => number;
+/** The point of a position on the ray `psi`: M + t·(E − M). */
+export declare const radialPoint: (ellipse: RadialEllipse, psi: number, position: number) => Point;

package/dist/components/organisms/ColorPicker/useGradientEditor.d.ts

@@ -0,0 +1,89 @@
+import { Ref } from 'vue';
+import { ColorPickerGradient, ColorPickerPreset } from './gradient';
+/** A stop as the editor keeps it: with an id, so it stays itself while it moves. */
+export interface GradientEditorStop {
+    id: number;
+    color: string;
+    position: number;
+    preset?: ColorPickerPreset;
+}
+/**
+ * State and actions of the picker's gradient mode. The stops are kept in the
+ * order of their handles in the DOM, which is only brought back in line with
+ * their positions once an action is over (`settle`): a dragged stop that passes
+ * another keeps its id, colour, selection and focus. What reaches the model is
+ * always in order of position, ties in the order they had before.
+ *
+ * `value` is the model. A change from outside is merged into the stops that are
+ * there, so ids survive a round trip through the parent; a different number of
+ * stops starts over. While `value` is unset `start` (or the default gradient)
+ * is shown and nothing is written until the first action.
+ */
+export declare const useGradientEditor: (options: {
+    value: Ref<ColorPickerGradient | undefined>;
+    selectedIndex: Ref<number>;
+    /** What to show while `value` is unset; the default gradient without it. */
+    start?: () => ColorPickerGradient | undefined;
+}) => {
+    type: Ref<"linear" | "radial", "linear" | "radial">;
+    angle: Ref<number, number>;
+    centerX: Ref<number, number>;
+    centerY: Ref<number, number>;
+    stops: Ref<{
+        id: number;
+        color: string;
+        position: number;
+        preset?: {
+            key: string;
+            label: string;
+        } | undefined;
+    }[], GradientEditorStop[] | {
+        id: number;
+        color: string;
+        position: number;
+        preset?: {
+            key: string;
+            label: string;
+        } | undefined;
+    }[]>;
+    sorted: import('vue').ComputedRef<{
+        id: number;
+        color: string;
+        position: number;
+        preset?: {
+            key: string;
+            label: string;
+        } | undefined;
+    }[]>;
+    snapshot: import('vue').ComputedRef<ColorPickerGradient>;
+    selectedId: Ref<number, number>;
+    centerSelected: Ref<boolean, boolean>;
+    selected: import('vue').ComputedRef<{
+        id: number;
+        color: string;
+        position: number;
+        preset?: {
+            key: string;
+            label: string;
+        } | undefined;
+    } | undefined>;
+    selectedOrder: import('vue').ComputedRef<number>;
+    canAdd: import('vue').ComputedRef<boolean>;
+    canRemove: import('vue').ComputedRef<boolean>;
+    neighbourColor: import('vue').ComputedRef<string>;
+    select: (id: number) => void;
+    selectCenter: () => void;
+    settle: () => void;
+    setType: (next: ColorPickerGradient["type"]) => void;
+    setAngle: (next: number) => void;
+    setCenter: (x: number, y: number) => void;
+    moveStop: (id: number, position: number) => void;
+    setGeometry: (positions: Map<number, number>, nextAngle?: number) => void;
+    addStop: (position?: number) => number | null;
+    removeStop: (id: number) => number | null;
+    reverse: () => void;
+    setStopColor: (color: string, preset?: ColorPickerPreset) => void;
+    setColorOf: (id: number, color: string, preset?: ColorPickerPreset) => void;
+    resetSession: () => void;
+};
+export type GradientEditor = ReturnType<typeof useGradientEditor>;

package/dist/index.d.ts

@@ -14,6 +14,9 @@ export type { NexxtPageMockupType } from './components/molecules/PageMockup/Page
 export type { NexxtPickerGroupData, NexxtPickerItemData, } from './components/molecules/PickerList/PickerList.vue';
 export type { NexxtTreeMove, NexxtTreeNode, NexxtTreeProps, NexxtTreeSlots, } from './components/molecules/Tree/Tree.vue';
 export type { NexxtPlaceholderGroup, NexxtPlaceholderInputMessages, NexxtPlaceholderInputProps, } from './components/molecules/PlaceholderInput/PlaceholderInput.vue';
+export type { ColorFormat, ColorPickerGradient, ColorPickerGradientMessages, ColorPickerGradientStop, ColorPickerFillMode, ColorPickerPreset, ColorSuggestions, } from './components/organisms/ColorPicker/ColorPicker.vue';
+export { gradientClassToCss, looksLikeGradientClass, parseGradientClass, } from './components/editor/molecules/EditorColor/gradientClass';
+export type { GradientClass, GradientClassColor, GradientClassStop, GradientClassType, } from './components/editor/molecules/EditorColor/gradientClass';
 export { EDITOR_ALIGNMENT_POSITIONS } from './components/editor/molecules/EditorAlignmentGrid/EditorAlignmentGrid.vue';
 export type { EditorAlignmentDirection, EditorAlignmentGridMessages, EditorAlignmentMode, EditorAlignmentPosition, EditorAlignmentValue, } from './components/editor/molecules/EditorAlignmentGrid/EditorAlignmentGrid.vue';
 export { EDITOR_ALIGN_ITEMS_OPTIONS } from './components/editor/molecules/EditorAlignItems/EditorAlignItems.vue';
@@ -28,7 +31,7 @@ export { EDITOR_FLEX_DIRECTION_OPTIONS } from './components/editor/molecules/Edi
 export type { EditorFlexDirectionMessages, EditorFlexDirectionValue, } from './components/editor/molecules/EditorFlexDirection/EditorFlexDirection.vue';
 export { EDITOR_GAP_STEPS } from './components/editor/molecules/EditorGap/EditorGap.vue';
 export type { EditorGapMessages, EditorGapValue, } from './components/editor/molecules/EditorGap/EditorGap.vue';
-export type { EditorColorLiteralValue, EditorColorMessages, EditorColorProperty, EditorColorRole, EditorColorRoleValue, EditorColorThemeRole, EditorColorValue, } from './components/editor/molecules/EditorColor/EditorColor.vue';
+export type { EditorColorFillMode, EditorColorGradientMessages, EditorColorGradientValue, EditorColorLinearGradientValue, EditorColorLiteralValue, EditorColorMessages, EditorColorProperty, EditorColorRadialGradientValue, EditorColorRole, EditorColorRoleValue, EditorColorThemeRole, EditorColorValue, } from './components/editor/molecules/EditorColor/EditorColor.vue';
 export { EDITOR_BORDER_STEPS } from './components/editor/molecules/EditorBorder/EditorBorder.vue';
 export type { EditorBorderMessages, EditorBorderWidth, } from './components/editor/molecules/EditorBorder/EditorBorder.vue';
 export { EDITOR_HEADING_TYPE_OPTIONS } from './components/editor/molecules/EditorHeadingType/EditorHeadingType.vue';