@zeroman.yang/react-auto-components 0.1.1 → 0.1.3

package/dist/core/registry.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import type { QueryNode } from "./query";
+/**
+ * Functions for a column `component` key. A function set on the column wins.
+ * `row` is the row object the host registered this renderer for.
+ */
+export interface ColumnRegistry {
+    render?: (value: unknown, row: object, index: number) => ReactNode;
+    format?: (value: unknown, row: object) => string | number;
+    sort?: (a: object, b: object) => number;
+    exportFormat?: (row: object) => unknown;
+}
+/** Query passed to a registered table source. Same shape as `TableQuery`. */
+export interface SourceQuery {
+    pageIndex: number;
+    pageSize: number;
+    sort: {
+        id: string;
+        desc: boolean;
+    }[];
+    filter: QueryNode;
+}
+/**
+ * Remote page loader registered on `config.sources`.
+ * Resolve `{ rows, total }`. `total` is the full filtered count.
+ * Reject to show `error.message` and a retry button.
+ */
+export type SourceLoader = (query: SourceQuery, context: {
+    signal: AbortSignal;
+}) => Promise<{
+    rows: object[];
+    total: number;
+}>;

package/dist/core/testid.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Playwright id. `config.t` and the visible label do not change it.
+ * `racTestId("field", "name")` is `rac-field-name`. `racTestId("add")` is `rac-add`.
+ */
+export declare function racTestId(part: string, name?: string): string;

package/dist/core/types.d.ts

@@ -1,40 +1,348 @@
 import type { CSSProperties, ReactNode } from "react";
+/** Loose record used by custom field renderers registered on the provider. */
 export type Values = Record<string, unknown>;
+/**
+ * Control height token.
+ * Default `"medium"` comes from `AutoConfigProvider` (`config.size`).
+ */
 export type ComponentSize = "small" | "medium" | "large";
+/**
+ * Vertical spacing token for forms, menus, tabs, and chat.
+ * Default `"comfortable"`. Tables use {@link TableDensity} instead.
+ */
 export type ComponentDensity = "comfortable" | "compact";
+/**
+ * Table row spacing. `"normal"` is the table default when no provider density is set.
+ * A provider `density: "compact"` maps to table `"compact"`; `"comfortable"` maps to `"normal"`.
+ */
 export type TableDensity = "compact" | "normal" | "comfortable";
+/**
+ * Label layout shared by `AutoForm` and `AutoSearch`.
+ * Defaults: `labelPosition` `"top"`, `labelWidth` `"auto"` (measured, capped at 45% of the field).
+ */
 export interface AutoFormLayout {
+    /** `"top"` stacks the label. `"left"` puts it beside the control. Default `"top"`. */
     labelPosition?: "top" | "left";
+    /** Used when `labelPosition` is `"left"`. Default `"right"` for left labels, otherwise `"left"`. */
     labelAlign?: "left" | "right";
+    /**
+     * Left-label column width. `"auto"` measures the longest label.
+     * A number is pixels. A string is any CSS width (`"8rem"`).
+     */
     labelWidth?: CSSProperties["width"];
     density?: ComponentDensity;
     size?: ComponentSize;
 }
+/** String keys of the value object. Symbols and numbers are not field names. */
 export type FieldName<T> = Extract<keyof T, string>;
+/**
+ * A static value, or a function of the current form values.
+ * Functions run during render. Keep them pure.
+ */
 export type Dynamic<V, T> = V | ((values: Readonly<T>) => V);
+/**
+ * Hide or disable a field, column, tab, or menu item.
+ * Both lists are AND-ed: every listed role and permission must pass `canAccess`.
+ * Default `canAccess` returns true for everything.
+ */
 export interface Access {
+    /** Visible when the user has every role. Omit to skip the role check. */
     roles?: readonly string[];
+    /** Visible when the user has every permission. Omit to skip the permission check. */
     permissions?: readonly string[];
 }
+/**
+ * One choice. `value` keeps boolean and numeric identity (`false` and `0` are selectable).
+ * `children` is only read by `type: "cascader"`.
+ */
 export interface Option {
     value: string | number | boolean;
     label: string;
     disabled?: boolean;
+    /** Next cascader column. Ignored by select, radio, and checkbox. */
     children?: readonly Option[];
 }
+/**
+ * Widget id. Omit it and the field renders as a text input.
+ * Illegal combinations (`select` without `options`, a scalar on `daterange`) are rejected by {@link Field}.
+ */
 export type FieldType = "input" | "email" | "textarea" | "integer" | "float" | "percentage" | "progress" | "switch" | "select" | "select-v2" | "radio" | "checkbox" | "cascader" | "autocomplete" | "date" | "datetime" | "daterange" | "datetimerange" | "upload" | "text" | "title" | "tip" | "button" | "append" | "custom";
+/** Widgets that render an empty control when `options` is missing. `options` is required. */
+export type ChoiceFieldType = "select" | "select-v2" | "radio" | "checkbox" | "cascader";
+/** Value is a two-item `[start, end]`. A scalar string or number is rejected. */
+export type DateRangeFieldType = "daterange" | "datetimerange";
+/**
+ * How a search field compares. Default is `"eq"`, or `"in"` when the value is an array.
+ * `"between"` is legal only when the model field is a two-item tuple.
+ * `"isNull"` ignores the value and matches null or undefined.
+ */
+export type MatchOperator = "eq" | "in" | "contains" | "between" | "isNull";
+/**
+ * Recommended `[from, to]` / `[start, end]` value.
+ * A wider array type also passes {@link Field}; a scalar does not.
+ * Open ends may be `null`.
+ */
+export type Pair<T = string | number | null> = readonly [T, T];
+/** Props passed to `render` and to renderers registered on `AutoConfigProvider.config.fields`. */
 export interface FieldContext<T extends object> {
+    /** DOM id for the control and its `<label htmlFor>`. */
     id: string;
     value: unknown;
     values: Readonly<T>;
     onChange: (value: unknown) => void;
     disabled: boolean;
+    /** Present when this field failed validation. Also referenced by `aria-describedby`. */
     error?: string;
 }
-export interface FieldBase<T extends object> extends Access {
+type RangeOk<V> = 0 extends 1 & V ? true : [unknown] extends [V] ? true : NonNullable<V> extends readonly unknown[] ? true : false;
+/**
+ * Props every named field accepts.
+ * Type-specific props live on the variant (`options` on choice fields, `rows` on textarea).
+ * Putting them on the wrong variant is a TypeScript excess-property error.
+ */
+export interface FieldShared<T extends object, K extends FieldName<T> = FieldName<T>> extends Access {
+    /** Key of `T`. Title, tip, append, and button omit it. */
+    name: K;
+    /**
+     * Shown next to the control. Falls back to `name`.
+     * When `lang` is set, `config.t(lang, label)` is used instead.
+     */
+    label?: string;
+    /** Message key passed to `config.t`. `label` is the fallback. */
+    lang?: string;
+    /**
+     * Initial value when the form is uncontrolled. Must be `T[name]`.
+     * Ignored once `value` is passed. Cloned with `structuredClone`.
+     */
+    defaultValue?: T[K];
+    /** Hidden fields are not validated and are omitted from the search query. */
+    hidden?: Dynamic<boolean, T>;
+    /** Disabled fields stay visible but are not validated. */
+    disabled?: Dynamic<boolean, T>;
+    /**
+     * Blocks submit when the value is `undefined`, `null`, `""`, or an empty array.
+     * Hidden, disabled, and inaccessible fields are not checked.
+     */
+    required?: boolean;
+    placeholder?: string;
+    /** Grid columns this field spans. Default `1`. Clamped to the form's `columns`. */
+    span?: number;
+    /** Start on a new row and span the full grid. */
+    lineBreak?: boolean;
+    style?: CSSProperties;
+    className?: string;
+    /** Help text under the control. Also the body of `type: "tip"` and `type: "append"`. */
+    tip?: ReactNode;
+    /**
+     * Run after the required check, in order. Return an error string, or throw (the message is shown).
+     * A resolve of `undefined` passes. Later rules are skipped after the first failure.
+     */
+    rules?: readonly ((value: unknown, values: Readonly<T>) => string | undefined | Promise<string | undefined>)[];
+    /**
+     * Replace the built-in control. Called instead of `type`.
+     * Throwing here escapes the input handler; the previous form value stays.
+     */
+    render?: (context: FieldContext<T>) => ReactNode;
+    /**
+     * Key in `AutoConfigProvider` `config.fields`. Used when `render` is absent.
+     * The registered function receives this field's context.
+     */
+    component?: string;
+    /**
+     * After this field changes, return a partial value to patch other fields.
+     * Throw to reject the keystroke; the previous value stays.
+     */
+    onChange?: (value: unknown, values: T) => Partial<T> | void;
+    /**
+     * Search comparison. See {@link MatchOperator}.
+     * `"between"` requires `T[name]` to be a two-item tuple.
+     */
+    match?: MatchOperator;
+    /** Case-fold string comparisons. Only affects `"contains"` and `"eq"` style matches. */
+    ignoreCase?: boolean;
+    /** Also match rows where the field is null or undefined (`OR` with `isNull`). */
+    includeNull?: boolean;
+    /**
+     * Query these row keys instead of `name`, OR-ed together.
+     * Example: one "keyword" input searching `first` and `last`.
+     */
+    searchFields?: readonly string[];
+    /** Search panels hide this field behind "More" until the user expands them. */
+    more?: boolean;
+}
+/** Text input. This is the default when `type` is omitted. `autocomplete` shows `options` as suggestions, not a closed list. */
+export interface InputField<T extends object, K extends FieldName<T> = FieldName<T>> extends FieldShared<T, K> {
+    /**
+     * `"input"` is a text box. `"email"` uses the email keyboard. `"text"` is read-only.
+     * `"autocomplete"` is a text box plus an optional suggestion list.
+     */
+    type?: "input" | "email" | "text" | "autocomplete";
+    /** Suggestions for `"autocomplete"`. Not required. Other text types ignore this. */
+    options?: Dynamic<readonly Option[], T>;
+}
+/** Multi-line text. `rows` defaults to `3`. */
+export interface TextareaField<T extends object, K extends FieldName<T> = FieldName<T>> extends FieldShared<T, K> {
+    type: "textarea";
+    /** Visible lines. Default `3`. */
+    rows?: number;
+}
+/**
+ * Numeric control.
+ * `"integer"` uses step `1` and stores a number (`undefined` while empty).
+ * `"float"` and `"percentage"` store the raw decimal string so `"1."` can be typed.
+ * `"progress"` is a read-only meter; `max` defaults to `100`.
+ */
+export interface NumberField<T extends object, K extends FieldName<T> = FieldName<T>> extends FieldShared<T, K> {
+    type: "integer" | "float" | "percentage" | "progress";
+    min?: number;
+    max?: number;
+    /** Default `1` for `"integer"`. Floats have no default step. */
+    step?: number;
+}
+/** Boolean checkbox with `role="switch"`. The stored value is `true` or `false`. */
+export interface SwitchField<T extends object, K extends FieldName<T> = FieldName<T>> extends FieldShared<T, K> {
+    type: "switch";
+}
+/**
+ * Closed set of options. `options` is required at compile time.
+ * `"checkbox"` stores an array and keeps `false` as a real value.
+ * `"cascader"` stores the path array and reads `Option.children`.
+ * `"select-v2"` virtualizes long lists. `"multiple"` applies to `"select"` and `"select-v2"`.
+ */
+export interface ChoiceField<T extends object, K extends FieldName<T> = FieldName<T>> extends FieldShared<T, K> {
+    type: ChoiceFieldType;
+    /** Static list, or a function of the other values. An empty list renders no choices. */
+    options: Dynamic<readonly Option[], T>;
+    /** `"select"` / `"select-v2"` only. Stores an array of option values. */
+    multiple?: boolean;
+}
+/**
+ * One calendar value.
+ * `dateValue: "string"` (default) stores `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm`.
+ * `dateValue: "timestamp"` stores epoch milliseconds in local time.
+ */
+export interface DateField<T extends object, K extends FieldName<T> = FieldName<T>> extends FieldShared<T, K> {
+    type: "date" | "datetime";
+    /** Default `"string"`. */
+    dateValue?: "string" | "timestamp";
+    /** Buttons that call `onChange` with `value()`. Return the same shape as the field value. */
+    shortcuts?: readonly {
+        label: string;
+        value: () => unknown;
+    }[];
+}
+/**
+ * Two calendar values, `[start, end]`.
+ * The model field must be a two-item tuple (`Pair` or `[string, string]`). A scalar is a type error.
+ * Same `dateValue` rules as {@link DateField}.
+ */
+export interface DateRangeField<T extends object, K extends FieldName<T> = FieldName<T>> extends FieldShared<T, K> {
+    type: DateRangeFieldType;
+    dateValue?: "string" | "timestamp";
+    shortcuts?: readonly {
+        label: string;
+        value: () => unknown;
+    }[];
+}
+/**
+ * File input. Without `upload`, the stored value is the `File` list.
+ * `upload` runs on change. Rejecting it shows the error under the control and does not store a value.
+ * `reset()` aborts the `AbortSignal` and drops a late result.
+ */
+export interface UploadField<T extends object, K extends FieldName<T> = FieldName<T>> extends FieldShared<T, K> {
+    type: "upload";
+    /** Passed to `<input accept>`. Example: `"image/*"`. */
+    accept?: string;
+    multiple?: boolean;
+    /** Return the value to store. Throw or reject to keep the previous value and show the message. */
+    upload?: (files: File[], signal: AbortSignal) => Promise<unknown>;
+}
+/**
+ * Your control, via `render` or `component`.
+ * Neither is required by the type so a host can attach one later; dev mode warns when both are missing.
+ */
+export interface CustomField<T extends object, K extends FieldName<T> = FieldName<T>> extends FieldShared<T, K> {
+    type: "custom";
+}
+/**
+ * Printed when `daterange` is attached to a scalar model field.
+ * Assigning a string or number fails against `fix`. Do not construct this type.
+ */
+interface DateRangeMismatch<T extends object, K extends FieldName<T>> extends Omit<DateRangeField<T, K>, "defaultValue"> {
+    defaultValue: {
+        readonly code: "RAC-FIELD-RANGE";
+        readonly fix: "Type this field as a two-item tuple [start, end]. daterange rejects a scalar string or number.";
+    };
+}
+/**
+ * Printed when `match: "between"` is attached to a scalar model field.
+ * One member, so the error is this fix and not every other widget. Do not construct it.
+ */
+type BetweenError<T extends object, K extends FieldName<T>> = Omit<FieldShared<T, K>, "match"> & {
+    match: "between";
+    readonly "RAC-FIELD-BETWEEN": {
+        readonly code: "RAC-FIELD-BETWEEN";
+        readonly fix: "Type this field as a two-item tuple [from, to]. match between rejects a scalar.";
+    };
+};
+type DateRangeFor<T extends object, K extends FieldName<T>> = RangeOk<T[K]> extends true ? DateRangeField<T, K> : DateRangeMismatch<T, K>;
+type FieldVariant<T extends object, K extends FieldName<T>> = InputField<T, K> | TextareaField<T, K> | NumberField<T, K> | SwitchField<T, K> | ChoiceField<T, K> | DateField<T, K> | DateRangeFor<T, K> | UploadField<T, K> | CustomField<T, K>;
+type WithMatch<T extends object, K extends FieldName<T>> = RangeOk<T[K]> extends true ? FieldVariant<T, K> : (FieldVariant<T, K> & {
+    match?: Exclude<MatchOperator, "between">;
+}) | BetweenError<T, K>;
+/**
+ * One schema field.
+ *
+ * Discriminant is `type` (and `name`, and `match: "between"`).
+ * `type: "select"` without `options` errors on {@link ChoiceField} only.
+ * A scalar model field used as `"daterange"` or `match: "between"` errors with
+ * `RAC-FIELD-RANGE` or `RAC-FIELD-BETWEEN` and a one-line fix, not every widget.
+ * `name` still completes `defaultValue` as `T[name]`.
+ *
+ * {@link AnyField} plus `unsafeField` skip these checks. Dev warnings still run.
+ */
+export type Field<T extends object> = {
+    [K in FieldName<T>]: WithMatch<T, K>;
+}[FieldName<T>] | DisplayField<T>;
+/**
+ * No `name` and no value. `"title"` renders `label` as a heading.
+ * Do not add `defaultValue` here. An optional `undefined` default collapses `type` in error messages and hides `RAC-FIELD-RANGE`.
+ * `"tip"` and `"append"` render `tip`. `"button"` renders `label` and calls `onAction` on click.
+ * `onAction` throwing propagates to the click handler; the form value does not change.
+ */
+export interface DisplayField<T extends object> extends Access {
+    /** Display fields are not keys of T. A string name belongs on a value field. */
+    name?: undefined;
+    type: "title" | "tip" | "append" | "button";
+    label?: string;
+    tip?: ReactNode;
+    span?: number;
+    lineBreak?: boolean;
+    hidden?: Dynamic<boolean, T>;
+    disabled?: Dynamic<boolean, T>;
+    style?: CSSProperties;
+    className?: string;
+    /** Ignored. Present so a mixed field list can be read without narrowing. */
+    lang?: string;
+    required?: boolean;
+    rules?: FieldShared<T>["rules"];
+    onChange?: (value: unknown, values: T) => Partial<T> | void;
+    /** Ignored. Search panels only hide named fields. */
+    more?: boolean;
+    /** `"button"` click. Receives the current values. */
+    onAction?: (values: Readonly<T>) => void;
+}
+/**
+ * Unchecked field. Every prop is optional, so `type: "select"` without `options` compiles.
+ * This is the escape hatch. Pass it through {@link unsafeField} when a component asks for {@link Field}.
+ * Dev mode still warns about missing options, scalar ranges, and `match: "between"`.
+ */
+export interface AnyField<T extends object> extends Access {
+    name?: FieldName<T>;
     label?: string;
     lang?: string;
     type?: FieldType;
+    defaultValue?: unknown;
     hidden?: Dynamic<boolean, T>;
     disabled?: Dynamic<boolean, T>;
     required?: boolean;
@@ -46,7 +354,7 @@ export interface FieldBase<T extends object> extends Access {
     style?: CSSProperties;
     className?: string;
     tip?: ReactNode;
-    rules?: readonly ((value: unknown, values: Readonly<T>) => string | undefined | Promise<string | undefined>)[];
+    rules?: FieldShared<T>["rules"];
     render?: (context: FieldContext<T>) => ReactNode;
     component?: string;
     onChange?: (value: unknown, values: T) => Partial<T> | void;
@@ -63,31 +371,26 @@ export interface FieldBase<T extends object> extends Access {
     }[];
     onAction?: (values: Readonly<T>) => void;
     more?: boolean;
-    match?: "eq" | "in" | "contains" | "between" | "isNull";
+    match?: MatchOperator;
     ignoreCase?: boolean;
     includeNull?: boolean;
     searchFields?: readonly string[];
 }
-export type Field<T extends object> = {
-    [K in FieldName<T>]: FieldBase<T> & {
-        name: K;
-        defaultValue?: T[K];
-    };
-}[FieldName<T>] | (FieldBase<T> & {
-    name?: never;
-    type: "title" | "tip" | "append" | "button";
-    defaultValue?: never;
-});
-export type AnyField<T extends object> = FieldBase<T> & {
-    name?: FieldName<T>;
-    defaultValue?: unknown;
-};
+/**
+ * `localStorage` adapter used when `config.storage` is omitted.
+ * `get` returns `undefined` for missing and corrupt JSON. `set` / `remove` swallow quota errors.
+ */
 export interface StorageAdapter {
     get(key: string): unknown;
     set(key: string, value: unknown): void;
     remove(key: string): void;
 }
+/**
+ * Optional remote store for table settings. Keys already include the namespace, for example `my-app:table:orders`.
+ * `load` resolving `undefined` keeps the local copy. A rejection shows "Could not save settings" and a retry button.
+ */
 export interface SettingsAdapter {
     load(key: string): Promise<unknown>;
     save(key: string, value: unknown): Promise<void>;
 }
+export {};

package/dist/errors-BT5WUIOV.js

@@ -0,0 +1,28 @@
+//#region src/core/errors.ts
+var e = class extends Error {
+	code;
+	userKey;
+	constructor(e, t, r, i, a) {
+		super(n(e, t, r, i)), this.name = "RacError", this.code = t, this.userKey = a, process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test" && console.error(this.message);
+	}
+}, t = "https://github.com/Zeroman/react-auto-components/blob/main/docs/errors.md#";
+function n(e, n, r, i) {
+	return `[${e}] ${r}\nFix: ${i}\nCode: ${n}\nDocs: ${t}${n.toLowerCase()}`;
+}
+var r = /* @__PURE__ */ new Set();
+function i(e, t, i, a) {
+	if (process.env.NODE_ENV === "production") return;
+	let o = `${t}\0${i}`;
+	r.has(o) || (r.add(o), console.warn(n(e, t, i, a)));
+}
+function a() {
+	r.clear();
+}
+function o(e) {
+	return Array.isArray(e) ? `array(length=${e.length})` : e === null ? "null" : typeof e;
+}
+function s(t, n) {
+	return n instanceof e && n.userKey ? t(n.userKey) : t(n instanceof Error ? n.message : String(n));
+}
+//#endregion
+export { s as a, a as i, i as n, o, n as r, e as t };

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 export * from "./core/types";
+export * from "./core/registry";
+export * from "./core/testid";
+export * from "./core/errors";
 export * from "./core/config";
 export * from "./core/query";
 export * from "./core/AutoConfigProvider";
 export * from "./components/AutoForm";
-export * from "./components/AutoSearchPanel";
+export * from "./components/AutoSearch";
 export * from "./components/AutoDialog";
 export * from "./components/AutoTabs";
 export * from "./components/AutoMenu";