@navette-js/infolists 1.0.0-beta.3 → 1.0.0-beta.4

package/lib/index.d.ts

@@ -1,103 +1,341 @@
-import { Component, type ComponentContext } from '@navette-js/schemas';
-import { type ColorManager } from '@navette-js/support';
+import { Component, type ComponentContext, type Renderable } from '@navette-js/schemas';
+import { HtmlString, type AttrValue, type ClassList, type ColorManager, type Lazy } from '@navette-js/support';
 export declare const useColorManager: (manager: ColorManager) => void;
+type AttrMap = Record<string, AttrValue>;
+/** Option that may depend on the record and on the state item. */
+export type PerItem<T> = T | ((record: any, state: unknown) => T);
+/** `icon()` / `color()` of an icon entry: a value, a map of state values, or a function. */
+export type StateMap<T> = PerItem<T> | Record<string, T>;
+/** PHP `date()` format (`M j, Y`, `d/m/Y H:i`…), with English month and day names. A backslash escapes a character. */
+export declare function formatPhpDate(date: Date, format: string, timeZone?: string): string;
+/** Carbon `isoFormat()` format (`L`, `LLL`, `dddd D MMMM YYYY`…), in English. Text in `[brackets]` is kept as is. */
+export declare function formatIsoDate(date: Date, format: string, timeZone?: string): string;
+/** Content of an entry slot: a schema component, an action, a text (escaped) or an `HtmlString` (inserted as is). */
+export type EntrySlotItem = Component | Renderable | string | HtmlString;
+type SlotValue = EntrySlotItem | EntrySlotItem[] | null;
+export type EntrySlot = SlotValue | ((ctx: ComponentContext) => SlotValue | Promise<SlotValue>);
+type SlotName = 'aboveLabel' | 'belowLabel' | 'beforeLabel' | 'afterLabel' | 'aboveContent' | 'belowContent' | 'beforeContent' | 'afterContent';
 /** Base entry: a label and a value read from the record (dotted paths allowed) or computed. */
 declare abstract class Entry extends Component {
-    protected _label: string | null;
+    protected _label: Lazy<string | null, ComponentContext>;
     protected _state: ((ctx: ComponentContext) => unknown | Promise<unknown>) | null;
+    protected _default: unknown;
+    protected _hiddenLabel: Lazy<boolean, ComponentContext>;
+    protected _placeholder: string | null;
+    protected _url: Lazy<string | null, ComponentContext>;
+    protected _openUrlInNewTab: Lazy<boolean, ComponentContext>;
+    protected _tooltip: PerItem<string | null>;
+    protected _emptyTooltip: string | null;
+    protected _inlineLabel: Lazy<boolean, ComponentContext>;
+    protected _alignment: Lazy<string | null, ComponentContext>;
+    protected _hiddenJs: string | null;
+    protected _visibleJs: string | null;
+    protected _extraEntryWrapperAttributes: Record<string, string>;
+    protected _slots: Partial<Record<SlotName, EntrySlot>>;
     constructor(name: string);
     hasStatePath(): boolean;
-    label(label: string): this;
-    protected _hiddenLabel: boolean;
+    /** Label: a string or a function of the context. Escaped when rendered. */
+    label(label: Lazy<string | null, ComponentContext>): this;
     /** Keeps the label for screen readers only. */
-    hiddenLabel(condition?: boolean): this;
+    hiddenLabel(condition?: Lazy<boolean, ComponentContext>): this;
     /** Computed value; without it, the record attribute of the same name is shown. */
     state(resolver: (ctx: ComponentContext) => unknown | Promise<unknown>): this;
+    /** State used when the real state is `null` or `undefined`; it is displayed as if it were real. */
+    default(state: unknown): this;
+    /** Gray text shown when the state is empty. */
+    placeholder(text: string | null): this;
+    /** Makes the content a link. Only `http(s)`, `mailto` and relative URLs are rendered: any other scheme is ignored. */
+    url(url: Lazy<string | null, ComponentContext>, openInNewTab?: Lazy<boolean, ComponentContext> | null): this;
+    openUrlInNewTab(condition?: Lazy<boolean, ComponentContext>): this;
+    /** Tooltip on the content: a string, or a function of the record and the state item. */
+    tooltip(tooltip: PerItem<string | null>): this;
+    /** Tooltip shown on the content when the state is empty. */
+    emptyTooltip(tooltip: string | null): this;
+    /** Label next to the content instead of above it (from the `sm` breakpoint). */
+    inlineLabel(condition?: Lazy<boolean, ComponentContext>): this;
+    /** Content alignment: `start`, `center`, `end`, `left`, `right`, `justify` or `between`. */
+    alignment(alignment: Lazy<string | null, ComponentContext>): this;
+    alignStart(): this;
+    alignCenter(): this;
+    alignEnd(): this;
+    alignLeft(): this;
+    alignRight(): this;
+    alignJustify(): this;
+    /** Hides the entry in the browser while this JavaScript expression is true (`$get('role') !== 'staff'`). Written by the developer, never from user input. */
+    hiddenJs(expression: string | null): this;
+    /** Shows the entry in the browser only while this JavaScript expression is true. */
+    visibleJs(expression: string | null): this;
+    /** Attributes of the outer element of the entry wrapper (label and content). Values are escaped. */
+    extraEntryWrapperAttributes(attributes: Record<string, string>): this;
+    aboveLabel(content: EntrySlot): this;
+    belowLabel(content: EntrySlot): this;
+    beforeLabel(content: EntrySlot): this;
+    /** Content after the label, aligned to the end. */
+    afterLabel(content: EntrySlot): this;
+    aboveContent(content: EntrySlot): this;
+    belowContent(content: EntrySlot): this;
+    beforeContent(content: EntrySlot): this;
+    /** Content after the entry content, aligned to the end. */
+    afterContent(content: EntrySlot): this;
+    getLabel(): Promise<string>;
     protected getState(): Promise<unknown>;
-    /** Wraps the content with the entry label. */
-    protected wrap(content: string): string;
+    protected getExtraAttributesMap(): AttrMap;
+    protected getAlignment(): Promise<string | null>;
+    protected getEmptyAttributes(base: ClassList): AttrMap;
+    protected emptyHtml(base: ClassList): string;
+    /** Actions placed in the slots, so that they can be mounted (`schemaComponent` = entry key). */
+    getActions(): any[];
+    protected renderSlot(name: SlotName): Promise<string | null>;
+    /** Places the content in the entry wrapper: label column, content column, slots and link. */
+    protected wrapEmbeddedHtml(content: string): Promise<string>;
+    /** `hiddenJs()` / `visibleJs()`: the grid wrapper becomes a `<fieldset>` toggled by Alpine, as in Filament. */
+    toSchemaHtml(isVisible: boolean): Promise<string>;
 }
-/** Sanitizer applied to HTML an entry renders as is (`markdown()`). Without one, the content is escaped. */
+/**
+ * Sanitizer applied to the HTML an entry renders as is (`html()`, `markdown()`, `prose()`).
+ * Without one, `sanitizeHtml()` from `@navette-js/support` is used.
+ */
 export declare const useHtmlSanitizer: (sanitizer: ((html: string) => string) | null) => void;
-/** Read-only text: badge, color, icon, money, date, placeholder. */
+type NumericOptions = {
+    decimalPlaces?: number | null;
+    maxDecimalPlaces?: number | null;
+    decimalSeparator?: string | null;
+    thousandsSeparator?: string | null;
+    locale?: string | null;
+};
+type MoneyOptions = {
+    divideBy?: number | null;
+    locale?: string | null;
+    decimalPlaces?: number | null;
+};
+/** Read-only text: badge, color, icon, money, number, date, list, Markdown and HTML. */
 export declare class TextEntry extends Entry {
     private _badge;
     private _color;
     private _icon;
+    private _iconColor;
+    private _iconPosition;
     private _format;
-    private _money;
-    private _date;
-    private _placeholder;
+    private _formatter;
+    private _formatterKind;
+    private _isDate;
+    private _isMoney;
+    private _isNumeric;
+    private _timezone;
+    private _prefix;
+    private _suffix;
+    private _prose;
+    private _markdown;
+    private _html;
+    private _characterLimit;
+    private _wordLimit;
+    private _listWithLineBreaks;
+    private _bulleted;
+    private _listLimit;
+    private _expandableLimitedList;
+    private _separator;
+    private _copyable;
+    private _copyableState;
+    private _copyMessage;
+    private _copyMessageDuration;
+    private _size;
+    private _weight;
+    private _fontFamily;
+    private _lineClamp;
+    private _wrap;
     static make(name: string): TextEntry;
     badge(condition?: boolean): this;
-    color(color: string | ((record: any) => string)): this;
-    icon(resolver: (record: any) => string | null): this;
-    formatStateUsing(formatter: (ctx: {
+    /** Text (or badge) color: a name, or a function of the record and the state item. */
+    color(color: PerItem<string | null>): this;
+    /** Heroicon before the text: a name, or a function of the record and the state item returning a name or `null`. */
+    icon(icon: PerItem<string | null>): this;
+    iconColor(color: PerItem<string | null>): this;
+    iconPosition(position: 'before' | 'after'): this;
+    /** Displayed text computed from the raw state; it takes precedence over date, number and money formatting. */
+    formatStateUsing(formatter: ((ctx: {
         state: unknown;
         record: any;
-    }) => string): this;
-    money(currency?: string): this;
-    date(condition?: boolean): this;
-    placeholder(text: string | null): this;
-    private _dateTime;
-    private _time;
-    private _suffix;
-    dateTime(condition?: boolean): this;
-    time(format?: string): this;
-    suffix(text: string | null): this;
-    private _prose;
-    private _markdown;
-    /** Typographic styling of the content (`fi-prose`). */
-    prose(condition?: boolean): this;
+    }) => unknown) | null): this;
+    private setFormatter;
+    private dateFormatter;
+    /** Date in a PHP format, `M j, Y` by default ("Mar 5, 2024"). `false` turns date formatting off. */
+    date(format?: string | boolean | null, timezone?: string | null): this;
+    /** Date and time, `M j, Y H:i:s` by default. */
+    dateTime(format?: string | boolean | null, timezone?: string | null): this;
+    /** Time, `H:i:s` by default. */
+    time(format?: string | null, timezone?: string | null): this;
+    /** Date in a Carbon `isoFormat()` format, `L` by default ("03/05/2024"). */
+    isoDate(format?: string | null, timezone?: string | null): this;
+    /** Date and time in an `isoFormat()` format, `LLL` by default ("March 5, 2024 10:11 AM"). */
+    isoDateTime(format?: string | null, timezone?: string | null): this;
+    /** Time in an `isoFormat()` format, `LT` by default ("10:11 AM"). */
+    isoTime(format?: string | null, timezone?: string | null): this;
+    /** Relative date: "2 days ago". */
+    since(timezone?: string | null): this;
+    private dateTooltipFor;
+    /** Tooltip with the date in a PHP format (`M j, Y` by default). */
+    dateTooltip(format?: string | null, timezone?: string | null): this;
+    dateTimeTooltip(format?: string | null, timezone?: string | null): this;
+    timeTooltip(format?: string | null, timezone?: string | null): this;
+    isoDateTooltip(format?: string | null, timezone?: string | null): this;
+    isoDateTimeTooltip(format?: string | null, timezone?: string | null): this;
+    isoTimeTooltip(format?: string | null, timezone?: string | null): this;
+    sinceTooltip(timezone?: string | null): this;
+    /** IANA time zone in which dates are displayed (`UTC` by default). */
+    timezone(timezone: string | null): this;
+    /**
+     * Formatted number. `numeric(2)`: two decimal places. Options: `decimalPlaces`, `maxDecimalPlaces`, `locale` (`en-US` by default),
+     * or `decimalSeparator` / `thousandsSeparator` for fixed separators. `false` turns number formatting off.
+     */
+    numeric(options?: boolean | number | null | NumericOptions): this;
     /**
-     * Rich text content, rendered as HTML after the sanitizer set with `useHtmlSanitizer()`.
-     * Existing HTML is kept (sanitized) and plain text becomes paragraphs; Markdown syntax itself is not converted.
+     * Amount of money in a currency (`usd` by default). `divideBy`: divides the state first (`100` for cents);
+     * `locale` (`en-US` by default) and `decimalPlaces` may be passed after it, or in an options object.
      */
+    money(currency?: string | ((record: any) => string), divideBy?: number | MoneyOptions | null, locale?: string | null, decimalPlaces?: number | null): this;
+    /** Text before the formatted state. A string is escaped; an `HtmlString` is inserted as is. */
+    prefix(text: string | HtmlString | null): this;
+    /** Text after the formatted state. A string is escaped; an `HtmlString` is inserted as is. */
+    suffix(text: string | HtmlString | null): this;
+    /** Truncates the text to `length` characters, followed by `end`. */
+    limit(length?: number | null, end?: string): this;
+    /** Truncates the text to a number of words, followed by `end`. */
+    words(words?: number | null, end?: string): this;
+    /** Clamps the text to a number of lines. */
+    lineClamp(lines: number | null): this;
+    /** `false`: long text does not wrap onto several lines. */
+    wrap(condition?: boolean): this;
+    /** Text size: `xs`, `sm` (default), `md` (or `base`) or `lg`. */
+    size(size: PerItem<string | null>): this;
+    /** Font weight: `thin`, `extralight`, `light`, `normal`, `medium`, `semibold`, `bold`, `extrabold` or `black`. */
+    weight(weight: PerItem<string | null>): this;
+    /** Font family: `sans`, `serif` or `mono`. */
+    fontFamily(family: PerItem<string | null>): this;
+    /** Typographic styling of rich content (`fi-prose`); the state is rendered as sanitized HTML. */
+    prose(condition?: boolean): this;
+    /** Renders Markdown as HTML. HTML in the state (from a rich editor) is sanitized instead. */
     markdown(condition?: boolean): this;
-    private _copyable;
-    private _numeric;
+    /** Renders the state as HTML, after it has been sanitized. */
+    html(condition?: boolean): this;
+    /** Each value of a list on its own line. */
+    listWithLineBreaks(condition?: boolean): this;
+    /** Bulleted list (implies line breaks). */
+    bulleted(condition?: boolean): this;
+    /** Shows only the first values of a list, followed by "and N more". */
+    limitList(limit?: number | null): this;
+    /** With `limitList()` and line breaks: a link reveals the other values. */
+    expandableLimitedList(condition?: boolean): this;
+    /** Splits a string state into a list on this separator. */
+    separator(separator?: string | null): this;
     /** Clicking copies the value to the clipboard. */
-    copyable(condition?: boolean): this;
-    /** Formatted number (thousands separators), aligned as a number. */
-    numeric(condition?: boolean): this;
+    copyable(condition?: PerItem<boolean>): this;
+    /** Value copied, when it differs from the displayed text. */
+    copyableState(state: PerItem<string | null>): this;
+    copyMessage(message: string | null): this;
+    copyMessageDuration(milliseconds: number): this;
+    /** Displayed text of a state item, and whether it is (sanitized) HTML. */
+    private formatItem;
     toHtml(): Promise<string>;
 }
-/** Color swatch: only hex or simple functional colors are injected into the style attribute. */
+/** Color swatch: only hex or simple functional colors are displayed. */
 export declare class ColorEntry extends Entry {
-    private _placeholder;
+    private _copyable;
+    private _copyableState;
+    private _copyMessage;
+    private _copyMessageDuration;
+    private _wrap;
     static make(name: string): ColorEntry;
-    placeholder(text: string | null): this;
+    /** Clicking the swatch copies the color to the clipboard. */
+    copyable(condition?: PerItem<boolean>): this;
+    copyableState(state: PerItem<string | null>): this;
+    copyMessage(message: string | null): this;
+    copyMessageDuration(milliseconds: number): this;
+    wrap(condition?: boolean): this;
     toHtml(): Promise<string>;
 }
-/** Read-only image: only same-site (`/…`) or http(s) URLs are rendered. */
+/** Read-only images: only same-site (`/…`) or http(s) URLs are rendered. */
 export declare class ImageEntry extends Entry {
     private _height;
+    private _width;
     private _alt;
     private _circular;
+    private _square;
+    private _stacked;
+    private _ring;
+    private _overlap;
+    private _limit;
+    private _limitedRemainingText;
+    private _limitedRemainingTextSize;
+    private _defaultImageUrl;
+    private _extraImgAttributes;
+    private _wrap;
     static make(name: string): ImageEntry;
-    /** CSS height of the image (`8rem` by default). */
-    imageHeight(height: string): this;
-    alt(text: string | null): this;
+    /** Height of the images: a CSS length (`40px`, `2.5rem`…) or a number of pixels; `8rem` by default. Any other value is ignored. */
+    imageHeight(height: number | string | null): this;
+    /** Width of the images: a CSS length or a number of pixels. Any other value is ignored. */
+    imageWidth(width: number | string | null): this;
+    imageSize(size: number | string): this;
+    alt(text: PerItem<string | null>): this;
     circular(condition?: boolean): this;
+    /** Square images: the width is the height. */
+    square(condition?: boolean): this;
+    /** Overlapping images (`2.5rem` high by default). */
+    stacked(condition?: boolean): this;
+    /** Ring width of stacked images, from 0 to 8. */
+    ring(width: number | null): this;
+    /** Overlap of stacked images, from 0 to 8 (2 by default). */
+    overlap(overlap: number | null): this;
+    /** Maximum number of images displayed. */
+    limit(limit?: number | null): this;
+    /** Shows "+N" after the limited images; `size`: `xs`, `sm` (default), `md` or `lg`. */
+    limitedRemainingText(condition?: boolean, size?: string | null): this;
+    /** Image displayed when the state is empty. */
+    defaultImageUrl(url: Lazy<string | null, ComponentContext>): this;
+    /** Extra `<img>` attributes (`loading`, `class`, `data-*`, `aria-*`…). Event handlers, `style` and sources are ignored; values are escaped. */
+    extraImgAttributes(attributes: Record<string, string>): this;
+    wrap(condition?: boolean): this;
     toHtml(): Promise<string>;
 }
-/** Icon based on the value; `boolean()` shows a green check or a red cross. */
+/** Icons chosen from the state; `boolean()` shows a green check or a red cross. */
 export declare class IconEntry extends Entry {
     private _boolean;
+    private _icon;
+    private _color;
+    private _size;
+    private _trueIcon;
+    private _falseIcon;
+    private _trueColor;
+    private _falseColor;
+    private _listWithLineBreaks;
+    private _wrap;
     static make(name: string): IconEntry;
     boolean(condition?: boolean): this;
+    /** Icon: a Heroicon name, a map of state values to names, or a function of the record and the state item. */
+    icon(icon: StateMap<string | null>): this;
+    /** Color: a name, a map of state values to colors, or a function of the record and the state item. */
+    color(color: StateMap<string | null>): this;
+    /** Icon size: `xs`, `sm`, `md`, `lg` (default), `xl` or `2xl`. */
+    size(size: PerItem<string | null>): this;
+    /** Icon of a true state (`o-check-circle` by default); `false`: no icon. Implies `boolean()`. */
+    trueIcon(icon: string | false | null): this;
+    /** Icon of a false state (`o-x-circle` by default); `false`: no icon. Implies `boolean()`. */
+    falseIcon(icon: string | false | null): this;
+    /** Color of a true state (`success` by default). Implies `boolean()`. */
+    trueColor(color: string | null): this;
+    /** Color of a false state (`danger` by default). Implies `boolean()`. */
+    falseColor(color: string | null): this;
+    /** Each icon of a list on its own line. */
+    listWithLineBreaks(condition?: boolean): this;
+    wrap(condition?: boolean): this;
     toHtml(): Promise<string>;
 }
 /** Key/value pairs as a table: the state is an object (or its JSON form); a non-scalar value is shown as JSON. */
 export declare class KeyValueEntry extends Entry {
     private _keyLabel;
     private _valueLabel;
-    private _placeholder;
     static make(name: string): KeyValueEntry;
     keyLabel(label: string | null): this;
     valueLabel(label: string | null): this;
-    /** Text shown when there are no pairs ("No entries" by default). */
-    placeholder(text: string | null): this;
     /** @deprecated Use `placeholder()`. */
     emptyMessage(text: string | null): this;
     toHtml(): Promise<string>;
@@ -110,7 +348,6 @@ export declare class CodeEntry extends Entry {
     private _grammar;
     private _lightTheme;
     private _darkTheme;
-    private _placeholder;
     private _copyable;
     private _copyMessage;
     private _copyMessageDuration;
@@ -120,7 +357,6 @@ export declare class CodeEntry extends Entry {
     /** Theme class names only: without a highlighter, colors stay those of the default themes. */
     lightTheme(theme: string | null): this;
     darkTheme(theme: string | null): this;
-    placeholder(text: string | null): this;
     /** Clicking copies the code to the clipboard. */
     copyable(condition?: boolean): this;
     copyMessage(message: string | null): this;
@@ -142,23 +378,65 @@ export declare class ViewEntry extends Entry {
     }) => string | Promise<string>) | null): this;
     /** `false`: the function renders the whole entry, without the usual wrapper (label). */
     wrapped(condition?: boolean): this;
+    /** Places custom content in the entry wrapper (label, slots, link): for entry classes extending `ViewEntry`. */
+    protected wrap(content: string): Promise<string>;
     toHtml(): Promise<string>;
 }
-/** Column header of a table repeatable entry (same shape as `TableColumn` from @navette-js/forms). */
+/** Column of a table repeatable entry: a header label, an optional width and alignment. */
+export declare class TableColumn {
+    label: string;
+    private _width;
+    private _hiddenHeaderLabel;
+    private _wrapHeader;
+    private _alignment;
+    constructor(label: string);
+    static make(label: string): TableColumn;
+    /** Fixed width: a number of pixels, or a CSS length (`10rem`, `20%`). Any other value is ignored. */
+    width(width: number | string | null): this;
+    /** Keeps the header label for screen readers only. */
+    hiddenHeaderLabel(condition?: boolean): this;
+    /** Lets a long header label wrap onto several lines. */
+    wrapHeader(condition?: boolean): this;
+    /** Header alignment: `start`, `center` or `end`. */
+    alignment(alignment: string | null): this;
+    alignStart(): this;
+    alignCenter(): this;
+    alignEnd(): this;
+    getWidth(): string | null;
+    isHeaderLabelHidden(): boolean;
+    canHeaderWrap(): boolean;
+    getAlignment(): string | null;
+}
+/** Column header of a table repeatable entry: `TableColumn` from this package (or the one of @navette-js/forms). */
 export type RepeatableColumn = {
     label: string;
     getWidth(): string | null;
+    isHeaderLabelHidden?(): boolean;
+    canHeaderWrap?(): boolean;
+    getAlignment?(): string | null;
 };
 /**
- * Read-only list of items, as a table: one row per item of the array read from
- * the record, one cell per schema entry.
+ * Read-only list of items read from the record: cards in a grid (default), or a table (`table()`) with one row per item
+ * and one cell per entry.
  */
 export declare class RepeatableEntry extends Entry {
-    private _columns;
+    private _tableColumns;
     private _schema;
+    private _grid;
+    private _itemColumns;
+    private _contained;
     static make(name: string): RepeatableEntry;
-    table(columns: RepeatableColumn[]): this;
-    schema(entries: Entry[] | (() => Entry[])): this;
+    /** Renders the items as a table with these columns, in the order of the schema's entries. */
+    table(columns: RepeatableColumn[] | null): this;
+    /** Components repeated for each item. A function returns fresh instances for each item. */
+    schema(components: Component[] | (() => Component[])): this;
+    /** Card layout: number of item columns (from `lg` for a number, per breakpoint for an object); 2 when called without argument. */
+    grid(columns?: Record<string, number> | number | null): this;
+    /** Card layout: grid columns inside each item. */
+    columns(columns: Record<string, number> | number | null): this;
+    /** Card layout: `false` removes the card styling of the items. */
+    contained(condition?: boolean): this;
+    private itemSchema;
     toHtml(): Promise<string>;
 }
 export {};