@getaster/elements 0.3.0 → 0.4.0

package/dist/form/policy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Form-wide static edit defaults. A field's own defaults in
+ * [[object:FormField]] win over these, and a page rule outranks both.
+ */
+export interface FormPolicy {
+    /** Every field starts read-only unless its FormField or a page rule says otherwise. */
+    readonly readOnly?: boolean;
+    /** Every field starts disabled unless its FormField or a page rule says otherwise. */
+    readonly disabled?: boolean;
+}
+/** Which presentation surfaces the form shows, and how it lays them out. */
+export interface FormChrome {
+    /** Columns for sections without their own `columns`. Default `2`. */
+    readonly columns?: number;
+    /** Labels above their controls (`"top"`, the default) or beside them (`"start"`). */
+    readonly titleOrientation?: "top" | "start";
+    /** Draw each error under its field. Default `true`; false leaves the error summary as the only surface. */
+    readonly showInlineErrors?: boolean;
+    /** List the errors above the sections, each a button that focuses its field. Default `false`. */
+    readonly errorSummary?: boolean;
+    /** Move focus to the first invalid field when validation first finds errors. Default `false`. */
+    readonly autoFocus?: boolean;
+}
+export declare const DEFAULT_FORM_COLUMNS = 2;
+export declare function formColumns(chrome: FormChrome): number;
+export declare function titleOrientation(chrome: FormChrome): "top" | "start";
+export declare function inlineErrorsShown(chrome: FormChrome): boolean;
+export declare function errorSummaryShown(chrome: FormChrome): boolean;
+export declare function autoFocusOnError(chrome: FormChrome): boolean;

package/dist/form/policy.js

@@ -0,0 +1,16 @@
+export const DEFAULT_FORM_COLUMNS = 2;
+export function formColumns(chrome) {
+    return chrome.columns ?? DEFAULT_FORM_COLUMNS;
+}
+export function titleOrientation(chrome) {
+    return chrome.titleOrientation ?? "top";
+}
+export function inlineErrorsShown(chrome) {
+    return chrome.showInlineErrors !== false;
+}
+export function errorSummaryShown(chrome) {
+    return chrome.errorSummary === true;
+}
+export function autoFocusOnError(chrome) {
+    return chrome.autoFocus === true;
+}

package/dist/grid/appearance.d.ts

@@ -0,0 +1,365 @@
+import type { Entity, Field, KeyText, Value } from "@getaster/data";
+import { type DateFormat } from "../date/dates.ts";
+/** One class or several. A string may name space-separated classes. */
+export type ClassNames = string | readonly string[];
+/** How a column's values and header line up. */
+export type ColumnAlign = "start" | "center" | "end";
+/** The semantic tone a hilite or value-map entry names; CSS decides its look. */
+export type PresentationTone = "neutral" | "positive" | "caution" | "negative";
+/** How a plain-data match compares a record's field. */
+export type ValueMatchOperator = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "between" | "contains" | "empty" | "notEmpty";
+/**
+ * A presentation condition on one record field. `in` takes an array and
+ * `between` a two-item inclusive range; `empty` and `notEmpty` take no value.
+ * A JS-only predicate is the `test` hook of a class rule or hilite.
+ */
+export type ValueMatch = {
+    /** The record field to read. */
+    readonly field: string;
+    /** How the field's value is compared. */
+    readonly op: ValueMatchOperator;
+    /** The comparison value; an array for `in`, two values for `between`. */
+    readonly value?: Value | readonly Value[];
+};
+/** How a number is written: plain decimal (default), integer, percent or currency. */
+export type NumberFormatStyle = "decimal" | "integer" | "percent" | "currency";
+/**
+ * A declarative display format for a date or number column. It only applies
+ * to a matching field type; other values keep the grid's default text.
+ */
+export type ColumnFormat = {
+    /** A calendar date (`Edm.Date`). */
+    readonly kind: "date";
+    /** `"medium"` (default), `"short"` or `"iso"`, as [[type:DateFormat]]. */
+    readonly style?: DateFormat;
+} | {
+    /** A numeric field (integers, decimal, single and double). */
+    readonly kind: "number";
+    /** The display style; `"decimal"` (default). */
+    readonly style?: NumberFormatStyle;
+    /** ISO 4217 code for `"currency"`; defaults to `"GBP"`. */
+    readonly currency?: string;
+    /** Minimum fraction digits. */
+    readonly minimumFractionDigits?: number;
+    /** Maximum fraction digits; `"integer"` defaults it to `0`. */
+    readonly maximumFractionDigits?: number;
+};
+/** A value-map entry: display text alone, or text with a tone and classes. */
+export type ValueMapValue = string | {
+    /** The display text for the raw value. */
+    readonly label: string;
+    /** A semantic tone for the cell. */
+    readonly tone?: PresentationTone;
+    /** Extra classes for the cell. */
+    readonly class?: ClassNames;
+};
+/**
+ * Per-column display overrides, keyed by the raw value written as text
+ * (`String(value)`). Metadata allowed values remain the base for entries the
+ * map omits; an unknown value keeps the grid's default display.
+ */
+export type ColumnValueMap = Readonly<Record<string, ValueMapValue>>;
+/** A value-map lookup hit: text plus the optional tone and classes. */
+export type MappedValue = {
+    /** The display text. */
+    readonly label: string;
+    /** A semantic tone for the cell. */
+    readonly tone?: PresentationTone;
+    /** Extra classes for the cell. */
+    readonly class?: ClassNames;
+};
+/** The row a class rule or predicate sees. */
+export type RowStyleContext = {
+    /** The record drawn in the row. */
+    readonly entity: Entity;
+    /** The record's key. */
+    readonly key: KeyText;
+    /** The row's position in the grid as rendered. */
+    readonly index: number;
+};
+/** The cell a class rule or predicate sees. */
+export type CellStyleContext = RowStyleContext & {
+    /** The column's field name. */
+    readonly field: string;
+    /** The record's raw value for the field. */
+    readonly value: Value | undefined;
+};
+/** A plain-data row class rule, with a JS-only predicate where matching needs code. */
+export type RowClassRule = {
+    /** A condition on a record field. */
+    readonly when?: ValueMatch;
+    /** A JS-only predicate; combined with `when` when both are present. */
+    readonly test?: (row: RowStyleContext) => boolean;
+    /** The classes the rule adds when it matches. */
+    readonly class: ClassNames;
+};
+/** A plain-data cell class rule, with a JS-only predicate where matching needs code. */
+export type CellClassRule = {
+    /** A condition on a record field. */
+    readonly when?: ValueMatch;
+    /** A JS-only predicate; combined with `when` when both are present. */
+    readonly test?: (cell: CellStyleContext) => boolean;
+    /** The classes the rule adds when it matches. */
+    readonly class: ClassNames;
+};
+/**
+ * Static classes, an ordered list mixing static names, rules and JS-only
+ * predicates, or a JS-only predicate. Predicates are rejected by the
+ * composition catalog.
+ */
+export type RowClass = ClassNames | readonly (RowClassRule | string | ((row: RowStyleContext) => ClassNames | undefined))[] | ((row: RowStyleContext) => ClassNames | undefined);
+/** Static classes, an ordered list mixing names, rules and JS-only predicates, or a predicate. */
+export type CellClass = ClassNames | readonly (CellClassRule | string | ((cell: CellStyleContext) => ClassNames | undefined))[] | ((cell: CellStyleContext) => ClassNames | undefined);
+/**
+ * A status/traffic-light rule. Row-scoped rules mark the row; cell-scoped
+ * rules mark one column's cells. A plain-data `when` and a JS-only `test`
+ * combine with AND when both are present.
+ */
+export type Hilite = {
+    /** Where it applies: the row (default) or one column's cells. */
+    readonly scope?: "row" | "cell";
+    /** The column a cell-scoped hilite marks; required for `scope: "cell"`. */
+    readonly field?: string;
+    /** The condition, on any record field. */
+    readonly when?: ValueMatch;
+    /** A JS-only predicate over the record and its value for the matched field. */
+    readonly test?: (entity: Entity, value: Value | undefined) => boolean;
+    /** The tone to mark; the last matching hilite with a tone wins. */
+    readonly tone?: PresentationTone;
+    /** Extra classes, in declared order. */
+    readonly class?: ClassNames;
+};
+/** Presentation overrides for one column, keyed by field name. */
+export type ColumnPresentation = {
+    /** Header text; the metadata title by default. */
+    readonly title?: string;
+    /** Alignment for the header and cells; numeric fields default to the end. */
+    readonly align?: ColumnAlign;
+    /** Raw-value display overrides; metadata allowed values are the base. */
+    readonly valueMap?: ColumnValueMap;
+    /** A display format for date and number fields. */
+    readonly format?: ColumnFormat;
+    /** Classes for this column's cells: static, rules, or a JS-only predicate. */
+    readonly cellClass?: CellClass;
+};
+/**
+ * The grid's one presentation surface: per-column overrides, row and cell
+ * class hooks, and hilites. Every field is optional; `{}` keeps today's
+ * rendering. Plain data travels through the composition catalog; predicates
+ * are JavaScript-only.
+ */
+export type GridPresentation = {
+    /** Per-column overrides, by field name. */
+    readonly columns?: Readonly<Record<string, ColumnPresentation>>;
+    /** Classes for every record row: static, rules, or a JS-only predicate. */
+    readonly rowClass?: RowClass;
+    /** Classes for every record cell: static, rules, or a JS-only predicate. */
+    readonly cellClass?: CellClass;
+    /** Status rules, applied in declared order after the class hooks. */
+    readonly hilites?: readonly Hilite[];
+};
+/** The classes and tone a row or cell received from presentation configuration. */
+export type StyleDecoration = {
+    /** Classes in precedence order, without duplicates. */
+    readonly classes: readonly string[];
+    /** The last tone a matching hilite (or value-map entry) supplied. */
+    readonly tone?: PresentationTone;
+};
+/** The grid's overridable strings. Missing entries keep today's text; `{name}` is a placeholder. */
+export declare const GRID_LABEL_DEFAULTS: {
+    readonly toolbarLabel: "{label} view";
+    readonly expandAll: "Expand all";
+    readonly collapseAll: "Collapse all";
+    readonly sort: "Sort";
+    readonly filters: "Filters";
+    readonly filtersActive: "Filters ({count})";
+    readonly advancedFilter: "Advanced filter";
+    readonly columns: "Columns";
+    readonly views: "Views";
+    readonly groupsFailed: "Couldn’t load groups.";
+    readonly retryGroups: "Retry groups";
+    readonly treeSearching: "Finding where the matches are…";
+    readonly treeTooBroad: "Too many matches to show where they are. Narrow the filter.";
+    readonly treeSearchFailed: "Couldn’t find where the matches are. Change the filter to try again.";
+    readonly groupedBy: "Grouped by {field}";
+    readonly thenBy: "Then by {field}";
+    readonly stopGrouping: "Stop grouping";
+    readonly removeGrouping: "Remove grouping {field}";
+    readonly moveGroupingEarlier: "Move {field} grouping earlier";
+    readonly moveGroupingLater: "Move {field} grouping later";
+    readonly groupingRefused: "Grouping is refused.";
+    readonly removeRefusedGrouping: "{reason} Remove it from the saved view.";
+    readonly filterRefused: "This page doesn’t allow filtering.";
+    readonly criteriaNeedsRepair: "Saved filter needs repair. No matches will be returned.";
+    readonly notLoaded: "Not loaded";
+    readonly loading: "Loading…";
+    readonly aboutRows: "About {count} rows";
+    readonly atLeastRows: "{count}+ rows";
+    readonly row: "1 row";
+    readonly rows: "{count} rows";
+    readonly group: "1 group";
+    readonly groups: "{count} groups";
+    readonly groupedRows: "{rows} in {groups}";
+    readonly pages: "Pages";
+    readonly firstPage: "First page";
+    readonly previousPage: "Previous page";
+    readonly nextPage: "Next page";
+    readonly lastPage: "Last page";
+    readonly page: "Page {page}";
+    readonly pageOf: "Page {page} of {pages}";
+    readonly pageRows: " · rows {first}–{last} of {total}";
+    readonly sortRows: "Sort rows";
+    readonly noSortableColumns: "This grid has no sortable columns.";
+    readonly sortAction: "Sort {field}";
+    readonly sortActionNow: "Sort {field}, now {direction}";
+    readonly sortReverse: "Click to reverse";
+    readonly sortAscending: "Click to sort ascending";
+    readonly sortPriority: "Sort priority {priority}.";
+    readonly clearFieldSorting: "Clear {field} sorting";
+    readonly clearSorting: "Clear sorting";
+    readonly moveFieldUp: "Move {field} up";
+    readonly moveFieldDown: "Move {field} down";
+    readonly resetView: "Reset to the page’s view";
+    readonly savedViews: "Saved views";
+    readonly noSavedViews: "None yet. Shape the grid, then save it here by name.";
+    readonly deleteView: "Delete the view {name}";
+    readonly viewName: "Name for this view";
+    readonly viewNamePlaceholder: "Name this view";
+    readonly save: "Save";
+    readonly delete: "Delete";
+    readonly sortBy: "Sort by {field}";
+    readonly addToSort: "; Shift adds it to the sort";
+    readonly dragToMove: "Drag to move";
+    readonly dragToResize: "Drag its right edge to resize";
+    readonly columnOptions: "{field} column options";
+    readonly rowColumn: "{field} column";
+    readonly rowMenu: "Row";
+    readonly notFilterable: "Not filterable";
+    readonly filterField: "Filter {field}";
+    readonly chooseFilterDate: "Choose a date to filter {field}";
+    readonly menuSort: "Sort";
+    readonly ascending: "Ascending";
+    readonly descending: "Descending";
+    readonly directionAscending: "ascending";
+    readonly directionDescending: "descending";
+    readonly notSorted: "Not sorted";
+    readonly addToSortMenu: "Add to the sort";
+    readonly groupBy: "Group by {field}";
+    readonly freezeUpTo: "Freeze up to {field}";
+    readonly menuMove: "Move";
+    readonly moveLeft: "Left";
+    readonly moveRight: "Right";
+    readonly moveToStart: "To the start";
+    readonly moveToEnd: "To the end";
+    readonly menuWidth: "Width";
+    readonly wider: "Wider";
+    readonly narrower: "Narrower";
+    readonly fitSpace: "Fit the space";
+    readonly hideField: "Hide {field}";
+    readonly columnsEllipsis: "Columns…";
+    readonly firstColumn: "It's the first column.";
+    readonly lastColumn: "It's the last column.";
+    readonly sortServiceRefused: "{field} can’t be sorted by this service.";
+    readonly sortNavigationRefused: "{field} can’t be sorted until its related record’s display field is known.";
+    readonly sortPolicyRefused: "Sorting by {field} isn’t allowed on this page.";
+    readonly filterServiceRefused: "{field} can’t be filtered by this service.";
+    readonly filterPolicyRefused: "Filtering by {field} isn’t allowed on this page.";
+    readonly filterOperatorRefused: "{field} can’t be filtered by {operator} on this page.";
+    readonly groupSharedRefused: "{field} can’t be grouped in a grid over shared data.";
+    readonly groupUnknownRefused: "{field} can’t be grouped.";
+    readonly groupLongRefused: "{field} is too long to group.";
+    readonly groupPolicyRefused: "Grouping by {field} isn’t allowed on this page.";
+    readonly resizePolicyRefused: "Resizing {field} isn’t allowed on this page.";
+    readonly movePolicyRefused: "Moving {field} isn’t allowed on this page.";
+    readonly hideLastRefused: "The last visible column can’t be hidden.";
+    readonly hidePolicyRefused: "Hiding {field} isn’t allowed on this page.";
+    readonly freezePolicyRefused: "Freezing {field} isn’t allowed on this page.";
+    readonly freezeUnknownRefused: "{field} can’t be frozen.";
+    readonly freezeLastRefused: "At least one column must stay unfrozen.";
+    readonly loadFailed: "Couldn’t load rows.";
+    readonly retry: "Retry";
+    readonly groupLoadFailed: "Couldn’t load group.";
+    readonly retryGroup: "Retry group {group}";
+    readonly summaryLoadFailed: "Couldn’t load summaries.";
+    readonly summaryLoading: "Loading summaries…";
+    readonly summariesUpdated: "Summaries updated";
+    readonly retrySummaries: "Retry summaries";
+    readonly summaryRows: "Rows";
+    readonly summarySum: "Sum {field}";
+    readonly summaryMinimum: "Minimum {field}";
+    readonly summaryMaximum: "Maximum {field}";
+    readonly summaryAverage: "Average {field}";
+    readonly summaryDistinct: "Distinct {field}";
+    readonly summaryAria: "{label} summaries";
+    readonly empty: "";
+    readonly rowLoadFailed: "Could not load that row. Move to another row or retry.";
+    readonly hiddenTitle: "You can't see this value";
+    readonly hiddenValue: "Hidden";
+    readonly advancedApplied: "Advanced filter applied";
+    readonly advancedCleared: "Advanced filter cleared";
+    readonly sortedBy: "Sorted by {sorts}";
+    readonly sortEntry: "{field}, {direction}";
+    readonly sortSeparator: ", then ";
+    readonly dragPickedUp: "Picked up {field}. Drop it on another row to move it under that row, or on Top level to move it to the top level.";
+    readonly dragNotMoved: "{field} not moved.";
+    readonly foldersLimit: "Opened {limit} folders. Narrow the tree to open more.";
+    readonly foldersOpened: "All folders opened.";
+    readonly foldersClosed: "All folders closed.";
+    readonly expansionLimit: "Only {limit} {noun} can be open at once. Close one first.";
+    readonly driftSort: "Sorted by {field}";
+    readonly driftFilter: "Filtered by {field}";
+    readonly driftCriteria: "The advanced filter uses {field}";
+    readonly driftGroup: "Grouped by {field}";
+    readonly driftHidden: "Column {field} is hidden";
+    readonly driftFrozen: "Column {field} is frozen";
+    readonly driftEntry: "{what}: {reason}";
+    readonly driftNote: "The saved view can’t fully apply. {entries} The view keeps these settings and uses them again when the page allows it.";
+    readonly driftFallbackReason: "{field} can’t be used by the saved view.";
+    readonly dismiss: "Dismiss";
+};
+/** One overridable grid string: a key of [[constant:GRID_LABEL_DEFAULTS]]. */
+export type GridLabel = keyof typeof GRID_LABEL_DEFAULTS;
+/**
+ * The grid's label bag. Every entry is optional; a missing entry keeps
+ * today's string. `{name}` placeholders are filled from the event the string
+ * describes. This is a stopgap before full i18n, not an i18n engine: it
+ * carries no plural rules, number locale or direction.
+ */
+export type GridLabels = {
+    readonly [K in GridLabel]?: string;
+};
+/**
+ * Checks a [[type:GridPresentation]] value. With `allowFunctions` true, the
+ * JS-only class predicates and hilite tests are accepted; the composition
+ * catalog calls it without that, so plain-data shapes are all it can carry.
+ */
+export declare function validateGridPresentation(value: unknown, allowFunctions?: boolean): asserts value is GridPresentation;
+/** Checks a [[type:GridLabels]] value: known keys, string values only. */
+export declare function validateGridLabels(value: unknown): asserts value is GridLabels;
+/** One label, overridden or defaulted, with `{name}` placeholders filled. */
+export declare function labelText(labels: GridLabels, key: GridLabel, values?: Readonly<Record<string, string | number>>): string;
+/** Whether one record meets a plain-data match. */
+export declare function matchValue(match: ValueMatch, entity: Entity): boolean;
+/**
+ * Classes and tone for one record row: the row hook first, then row-scoped
+ * hilites in declared order. The last hilite with a tone wins.
+ */
+export declare function styleRow(presentation: GridPresentation, context: RowStyleContext): StyleDecoration;
+/**
+ * Classes and tone for one record cell: the grid cell hook, then the column
+ * hook, then a value-map entry, then cell-scoped hilites in declared order.
+ * The last tone wins.
+ */
+export declare function styleCell(presentation: GridPresentation, column: ColumnPresentation | undefined, context: CellStyleContext, mapped?: MappedValue): StyleDecoration;
+/**
+ * A value-map entry for a raw value, keyed by `String(value)`. `undefined`
+ * means the map has no entry: metadata allowed values and default formatting
+ * still apply.
+ */
+export declare function mappedValue(column: ColumnPresentation | undefined, value: Value | undefined): MappedValue | undefined;
+/**
+ * The text a value shows when no renderer, formatter or value-map entry
+ * applies. A date or number format overrides the matching type's default;
+ * everything else is [[staticMethod:formatValue]]'s text.
+ */
+export declare function cellText(field: Field | undefined, value: Value | undefined, format?: ColumnFormat): string;