@navette-js/support 0.0.0-stage → 1.0.0-beta.2

package/lib/index.d.ts

@@ -0,0 +1,165 @@
+/** Escapes `&`, `<`, `>`, `"` and `'` for HTML. */
+export declare function e(value: unknown): string;
+/** Trusted HTML string: views do not escape it again. */
+export declare class HtmlString {
+    html: string;
+    constructor(html: string);
+    toString(): string;
+}
+export declare const raw: (html: string) => HtmlString;
+/** Serializes a value into a JavaScript expression that is safe to embed in HTML. */
+export declare function js(value: unknown): string;
+export type ClassList = (string | false | null | undefined | Record<string, unknown>)[] | Record<string, unknown>;
+export declare function cls(list: ClassList): string;
+export type AttrValue = string | number | boolean | null | undefined;
+export declare class Attributes {
+    private map;
+    constructor(initial?: Record<string, AttrValue>);
+    get(key: string): AttrValue;
+    has(key: string): boolean;
+    /** Defaults come first, then existing attributes (`class` and `style` are concatenated); null/false defaults are skipped. */
+    merge(defaults: Record<string, AttrValue>): Attributes;
+    /** Adds (or replaces) an attribute at the end. */
+    set(key: string, value: AttrValue): Attributes;
+    private clone;
+    /** Appends classes after the existing ones; the attribute keeps its position, or goes last. */
+    class(list: ClassList): Attributes;
+    style(list: (string | false | null | undefined)[]): Attributes;
+    when(condition: unknown, fn: (a: Attributes) => Attributes): Attributes;
+    /** Grid container: `fi-grid` classes and `--cols-*` variables per breakpoint. */
+    grid(columns?: Record<string, number> | number | null): Attributes;
+    /** Grid column: `fi-grid-col` classes and `--col-span-*` variables per breakpoint. */
+    gridColumn(span?: Record<string, number | string> | number | string | null, isHidden?: boolean): Attributes;
+    /** Renders `key="value"` pairs; `true` becomes `key="key"` (or `""` for x-data and wire:*). Values are not escaped again, except `"`. */
+    toHtml(): string;
+    toString(): string;
+}
+export declare const attrs: (initial?: Record<string, AttrValue>) => Attributes;
+export type Lazy<T, C = any> = T | ((ctx: C) => T | Promise<T>);
+export declare function evaluate<T, C>(value: Lazy<T, C>, ctx: C): Promise<T>;
+export type Palette = Record<number, string>;
+export declare const Color: Record<string, Palette>;
+export declare const WCAG_AA_TEXT = 4.5;
+/** Converts `#rrggbb`, `rgb(r, g, b)` or `r, g, b` to `oklch(L C h)`, rounded to three decimals. */
+export declare function convertToOklch(color: string): string;
+/** Builds an eleven-shade palette from a single color, keeping its hue. */
+export declare function generatePalette(color: string): Palette;
+/** A ready-made palette, or a color (`#6366f1`, `rgb(…)`) from which a palette is generated. */
+export type ColorInput = Palette | string;
+export declare function convertToRgb(color: string): [number, number, number];
+/** Contrast ratio with luminance approximated by a 2.2 gamma (intentionally not the exact WCAG formula; shade choices depend on it). */
+export declare function calculateContrastRatio(c1: string, c2: string): number;
+export declare function isLight(color: string): boolean;
+/** Picks accessible background and text shades for a filled button. */
+export declare function buttonColorMap(palette: Palette, minRatio?: number): Record<string, number>;
+/** First shade of the palette with enough contrast against a surface. */
+export declare function findShade(palette: Palette, surface: string, options?: {
+    minRatio?: number;
+    maxShade?: number;
+    minShade?: number;
+    fromDarkest?: boolean;
+}): number | null;
+/** Color map of badges. */
+export declare function badgeColorMap(palette: Palette, gray: Palette): Record<string, number>;
+/** Color map of dropdown items. */
+export declare function dropdownItemColorMap(palette: Palette, gray: Palette): Record<string, number>;
+/** Color map of icon columns (non-text contrast, 3:1). */
+export declare function iconColumnColorMap(palette: Palette, gray: Palette): Record<string, number>;
+/** Color map of icon buttons (non-text contrast 3:1 on gray-50 / gray-700). */
+export declare function iconButtonColorMap(palette: Palette, gray: Palette): Record<string, number>;
+/** Color map of toggles (non-text contrast, 3:1). */
+export declare function toggleColorMap(palette: Palette, gray: Palette): Record<string, number>;
+export declare function linkColorMap(palette: Palette, gray: Palette): Record<string, number>;
+/** Outlined button: only the text color depends on the palette. */
+export declare function outlinedButtonColorMap(palette: Palette, gray: Palette): Record<string, number>;
+/** Color map of each colored component. */
+declare const COMPONENT_COLOR_MAPS: {
+    button: (palette: Palette) => Record<string, number>;
+    'button-outlined': typeof outlinedButtonColorMap;
+    badge: typeof badgeColorMap;
+    link: typeof linkColorMap;
+    'dropdown-item': typeof dropdownItemColorMap;
+    'icon-column': typeof iconColumnColorMap;
+    'icon-button': typeof iconButtonColorMap;
+    toggle: typeof toggleColorMap;
+    'stat-description': (palette: Palette, gray: Palette) => {
+        text: number;
+        'dark:text': number;
+    };
+    'stat-chart': () => {};
+    text: (palette: Palette, gray: Palette) => {
+        text: number;
+        'dark:text': number;
+    };
+};
+export type ColoredComponent = keyof typeof COMPONENT_COLOR_MAPS;
+/** Registers named palettes and computes the color classes of components. */
+export declare class ColorManager {
+    static DEFAULT_COLORS: Record<string, Palette>;
+    private colors;
+    private cache;
+    /** Per-request colors (theme picked by the user); they take precedence over the panel's colors. */
+    private scope;
+    register(colors: Record<string, ColorInput>): this;
+    /** Runs `fn` with colors that only apply to this request; `key` identifies the color set for caching. */
+    runWith<T>(key: string, colors: Record<string, ColorInput>, fn: () => T): T;
+    getColors(): Record<string, Palette>;
+    getColor(name: string): Palette | undefined;
+    /** Color classes of a colored component. */
+    getComponentClasses(component: ColoredComponent, color: string | null): string[];
+    /** `<style>` block defining the `--<color>-<shade>` variables, injected into `<head>`. */
+    renderCssVariables(): string;
+}
+/** Heroicons icon (`m-eye`, `o-user`, `s-…`, `c-…`) with the `fi-icon fi-size-<size>` classes. */
+export declare function icon(name: string, options?: {
+    size?: string;
+    attributes?: Attributes;
+}): string;
+/** Registers a non-Heroicons icon (brand logo, custom glyph): a full `<svg>` supplied by the application, never by end users (it is not sanitized). */
+export declare function registerIcon(name: string, svg: string): void;
+/** Loading spinner SVG. */
+export declare function loadingIndicator(attributes?: Attributes, size?: string): string;
+/** View registry: `filament-forms::components.text-input` resolves to an EJS file; override directories are checked first. */
+export declare class ViewRegistry {
+    private namespaces;
+    private overrides;
+    private compiled;
+    private shared;
+    namespace(name: string, dir: string): this;
+    /** Application override directory: `<dir>/<namespace>/<path>.ejs` replaces the package view. */
+    overrideFrom(dir: string): this;
+    share(data: Record<string, unknown>): this;
+    resolve(view: string): string;
+    render(view: string, data?: Record<string, unknown>): string;
+}
+export declare const views: ViewRegistry;
+/** Registers a callback applied to every instance of the class (and its subclasses) created afterwards by `make()`. */
+export declare function configureUsing<T>(cls: abstract new (...args: any[]) => T, configure: (instance: T) => void): void;
+/** Applies the global callbacks to a new instance, from the most general class to the most specific. */
+export declare function configured<T extends object>(instance: T): T;
+/** Forgets all global callbacks (for tests). */
+export declare function resetConfigurators(): void;
+/** What a render hook receives: the call's scopes (page, resource…) and the slot's data (`action`, `column`…). */
+export type RenderHookContext = {
+    scopes: unknown[];
+    data: Record<string, any>;
+};
+export type RenderHookCallback = (context: RenderHookContext) => string | null | undefined;
+/** Render hook registry. Unscoped hooks render everywhere; scoped hooks only when the call carries one of their scopes. */
+export declare class RenderHookRegistry {
+    private hooks;
+    register(name: string, hook: RenderHookCallback, scopes?: unknown | unknown[] | null): this;
+    /** Hooks to render for a call: unscoped first, then scope by scope, each hook once. */
+    collect(name: string, scopes: unknown[]): RenderHookCallback[];
+    has(name: string, scopes?: unknown | unknown[] | null): boolean;
+    render(name: string, scopes?: unknown | unknown[] | null, data?: Record<string, any>): string;
+    clear(): void;
+}
+/** Process-wide hooks (all panels). */
+export declare const renderHooks: RenderHookRegistry;
+/** Renders with an extra registry (the request panel's) on top of the process-wide hooks. */
+export declare function runWithRenderHooks<T>(registry: RenderHookRegistry, fn: () => T): T;
+/** Renders a slot: process-wide hooks, then the current panel's hooks. */
+export declare function renderHook(name: string, scopes?: unknown | unknown[] | null, data?: Record<string, any>): string;
+export declare function hasRenderHook(name: string, scopes?: unknown | unknown[] | null): boolean;
+export {};