@zeroman.yang/react-auto-components 0.1.0

package/dist/components/AutoTable/index.d.ts

@@ -0,0 +1,4 @@
+export { AutoTable } from "./AutoTable";
+export type * from "./types";
+export * from "./settings";
+export { collectExport, toCsv, toJson } from "./export";

package/dist/components/AutoTable/settings.d.ts

@@ -0,0 +1,34 @@
+import { type QueryNode } from "../../core/query";
+import type { TableSort } from "./types";
+export interface Layout {
+    order: string[];
+    hidden: string[];
+    widths: Record<string, number>;
+    pin: Record<string, "left" | "right" | null | undefined>;
+    density: "inherit" | "compact" | "normal" | "comfortable";
+}
+export interface ExportSettings {
+    columns: string[];
+    format: "csv" | "json" | "xlsx";
+    scope: "page" | "filtered" | "selected";
+    fileName: string;
+}
+export interface Presets<V> {
+    activeId: string;
+    version: string | number;
+    presets: {
+        id: string;
+        name: string;
+        value: V;
+    }[];
+}
+export interface TableSettings {
+    layout: Presets<Layout>;
+    sort: Presets<TableSort[]>;
+    filter: Presets<QueryNode>;
+    export: Presets<ExportSettings>;
+}
+export declare function initialSettings(keys: string[], base?: Partial<Layout>): TableSettings;
+export declare function active<V>(g: Presets<V>): V;
+export declare function replaceActive<V>(g: Presets<V>, value: V): Presets<V>;
+export declare function reconcileSettings(saved: unknown, keys: string[], versions: Partial<Record<keyof TableSettings, string | number>>, base?: Partial<Layout>): TableSettings;

package/dist/components/AutoTable/types.d.ts

@@ -0,0 +1,107 @@
+import type { AutoSearchPanelProps } from "../AutoSearchPanel";
+import type { CSSProperties, ReactNode, Ref } from "react";
+import type { Access, ComponentSize, Field, FieldName, Option, TableDensity } from "../../core/types";
+import type { QueryNode } from "../../core/query";
+export interface TableSort {
+    id: string;
+    desc: boolean;
+}
+export interface TableQuery {
+    pageIndex: number;
+    pageSize: number;
+    sort: TableSort[];
+    filter: QueryNode;
+}
+export type DataSource<T> = (query: TableQuery, context: {
+    signal: AbortSignal;
+}) => Promise<{
+    rows: T[];
+    total: number;
+}>;
+export type RowScope = "page" | "filtered" | "selected";
+export interface AutoColumn<T extends object> extends Access {
+    key: FieldName<T>;
+    label?: string;
+    header?: ReactNode;
+    type?: "text" | "number" | "date" | "datetime" | "percentage" | "progress";
+    width?: number;
+    minWidth?: number;
+    hidden?: boolean;
+    pin?: "left" | "right";
+    align?: "left" | "center" | "right";
+    sortable?: boolean;
+    filterable?: boolean;
+    options?: readonly Option[];
+    format?: (value: T[FieldName<T>], row: T) => string | number;
+    render?: (value: T[FieldName<T>], row: T, index: number) => ReactNode;
+    sort?: (a: T, b: T) => number;
+    export?: boolean;
+    exportFormat?: (row: T) => unknown;
+    summary?: boolean | ((rows: readonly T[]) => ReactNode);
+    merge?: boolean;
+    copyable?: boolean;
+}
+export interface RowAction<T> {
+    id: string;
+    label: string;
+    hidden?: (row: T) => boolean;
+    disabled?: (row: T) => boolean;
+    onClick: (row: T) => void | Promise<void>;
+}
+export interface AutoTableHandle<T> {
+    refresh(): void;
+    reset(): void;
+    scrollToRow(id: string): void;
+    getSelectedRows(): T[];
+    export(format: "csv" | "json" | "xlsx", scope?: RowScope): Promise<void>;
+}
+export interface TableBaseProps<T extends object> {
+    id: string;
+    columns?: readonly AutoColumn<T>[];
+    rowKey: FieldName<T> | ((row: T) => string);
+    title?: string;
+    pageSize?: number;
+    pagination?: boolean;
+    query?: TableQuery;
+    onQueryChange?: (query: TableQuery) => void;
+    virtual?: boolean;
+    /** Numeric values size the scroll area; "auto" fills a height-constrained parent. */
+    height?: number | "auto";
+    rowHeight?: number;
+    size?: ComponentSize;
+    density?: TableDensity;
+    searchFields?: readonly Field<T>[];
+    searchLayout?: Pick<AutoSearchPanelProps<T>, "columns" | "labelPosition" | "labelAlign" | "labelWidth" | "density" | "size">;
+    formFields?: readonly Field<T>[];
+    onAdd?: (values: T) => void | Promise<void>;
+    onEdit?: (row: T, values: T) => void | Promise<void>;
+    onDelete?: (rows: readonly T[]) => void | Promise<void>;
+    getChildren?: (row: T) => T[] | undefined;
+    renderExpanded?: (row: T) => ReactNode;
+    expandAll?: boolean;
+    onSelectionChange?: (rows: T[]) => void;
+    toolbar?: ReactNode;
+    rowActions?: readonly RowAction<T>[];
+    rowClassName?: (row: T) => string;
+    rowStyle?: (row: T) => CSSProperties;
+    rowLoading?: (row: T) => boolean;
+    summaryScope?: RowScope;
+    /** Server aggregates for the complete filtered result, keyed by column. */
+    summaryValues?: Partial<Record<FieldName<T>, ReactNode>>;
+    versions?: Partial<Record<"layout" | "sort" | "filter" | "export", string | number>>;
+    exportXlsx?: (data: {
+        headers: string[];
+        rows: unknown[][];
+    }, options: {
+        fileName: string;
+    }) => Promise<ArrayBuffer | Uint8Array>;
+    empty?: ReactNode;
+    ref?: Ref<AutoTableHandle<T>>;
+}
+export type AutoTableProps<T extends object> = TableBaseProps<T> & ({
+    data: readonly T[];
+    dataSource?: never;
+} | {
+    data?: never;
+    dataSource: DataSource<T>;
+});

package/dist/components/AutoTable/useTableData.d.ts

@@ -0,0 +1,9 @@
+import type { DataSource, TableQuery } from "./types";
+export declare function useTableData<T extends object>(data: readonly T[] | undefined, source: DataSource<T> | undefined, query: TableQuery): {
+    resolved: boolean;
+    rows: readonly T[];
+    total: number;
+    loading: boolean;
+    error: string;
+    refresh: () => void;
+};

package/dist/components/AutoTable/useTableSettings.d.ts

@@ -0,0 +1,7 @@
+import { type Layout, type TableSettings } from "./settings";
+export declare function useTableSettings(id: string, keys: string[], versions?: Partial<Record<keyof TableSettings, string | number>>, base?: Partial<Layout>): {
+    settings: TableSettings;
+    update: (next: TableSettings) => void;
+    error: string;
+    retry: () => void;
+};

package/dist/components/AutoTabs/index.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+import type { Access, ComponentDensity, ComponentSize } from "../../core/types";
+export interface AutoTab extends Access {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    badge?: ReactNode;
+    hidden?: boolean | (() => boolean);
+    disabled?: boolean;
+    content?: ReactNode;
+    /** A nested tab group rendered inside this tab's content panel. */
+    children?: readonly AutoTab[];
+    loading?: boolean;
+    onRefresh?: () => void;
+    defaultActive?: string;
+}
+export interface AutoTabsProps {
+    items: readonly AutoTab[];
+    value?: readonly string[];
+    defaultValue?: readonly string[];
+    onChange?: (path: readonly string[], item: AutoTab) => void;
+    /** Tab orientation. Use AutoMenu for hierarchical navigation. */
+    mode?: "horizontal" | "vertical";
+    keepMounted?: boolean;
+    extra?: ReactNode;
+    size?: ComponentSize;
+    density?: ComponentDensity;
+}
+export declare function AutoTabs({ items, value, defaultValue, onChange, mode, keepMounted, extra, size: ownSize, density: ownDensity, }: AutoTabsProps): import("react").JSX.Element;

package/dist/core/AutoConfigProvider.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import type { Access, AutoFormLayout, ComponentDensity, ComponentSize, FieldContext, SettingsAdapter, StorageAdapter, TableDensity, Values } from "./types";
+export interface TableGlobalConfig {
+    density?: TableDensity;
+    size?: ComponentSize;
+}
+export interface TabsGlobalConfig {
+    density?: ComponentDensity;
+    size?: ComponentSize;
+}
+export interface MenuGlobalConfig {
+    density?: ComponentDensity;
+    size?: ComponentSize;
+}
+export interface AutoServices {
+    namespace: string;
+    size?: ComponentSize;
+    density?: ComponentDensity;
+    table?: TableGlobalConfig;
+    tabs?: TabsGlobalConfig;
+    menu?: MenuGlobalConfig;
+    form: AutoFormLayout;
+    t: (key: string, fallback?: string) => string;
+    canAccess: (access: Access) => boolean;
+    storage: StorageAdapter;
+    settings?: SettingsAdapter;
+    notify: (message: string, level: "success" | "error") => void;
+    fields: Record<string, (context: FieldContext<Values>) => ReactNode>;
+}
+export declare function AutoConfigProvider({ config, children, }: {
+    config?: Partial<AutoServices>;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useAutoConfig(): AutoServices;

package/dist/core/config.d.ts

@@ -0,0 +1,10 @@
+import type { Option, StorageAdapter } from "./types";
+export declare function resolve<V, T>(value: V | ((values: T) => V) | undefined, values: T, fallback: V): V;
+export declare function defaults<T extends object>(fields: readonly {
+    name?: string;
+    defaultValue?: unknown;
+}[], initial?: Partial<T>): T;
+export declare function normalizeOptions(options: readonly Option[]): readonly Option[];
+export declare const safeStorage: StorageAdapter;
+export declare function errorMessage(error: unknown): string;
+export declare function equal(a: unknown, b: unknown): boolean;

package/dist/core/i18n.d.ts

@@ -0,0 +1,2 @@
+/** Translate built-in text without changing the provider's existing t contract. */
+export declare function useAutoText(): (message: string, values?: readonly unknown[]) => string;

package/dist/core/query.d.ts

@@ -0,0 +1,24 @@
+export type QueryNode = {
+    kind: "condition";
+    field: string;
+    operator: "eq" | "in" | "contains" | "between" | "isNull";
+    value: unknown;
+    ignoreCase?: boolean;
+} | {
+    kind: "group";
+    operator: "and" | "or";
+    children: readonly QueryNode[];
+};
+export declare const emptyQuery: QueryNode;
+export interface SearchField {
+    name?: string;
+    match?: "eq" | "in" | "contains" | "between" | "isNull";
+    ignoreCase?: boolean;
+    includeNull?: boolean;
+    searchFields?: readonly string[];
+}
+export declare function buildQuery(values: object, fields: readonly SearchField[]): QueryNode;
+export declare function matchesQuery(row: object, q: QueryNode): boolean;
+export declare function serializeRsql(q: QueryNode): string;
+/** Validate persisted/untrusted query shapes before evaluating them. */
+export declare function isQueryNode(value: unknown, keys?: readonly string[], depth?: number): value is QueryNode;

package/dist/core/types.d.ts

@@ -0,0 +1,93 @@
+import type { CSSProperties, ReactNode } from "react";
+export type Values = Record<string, unknown>;
+export type ComponentSize = "small" | "medium" | "large";
+export type ComponentDensity = "comfortable" | "compact";
+export type TableDensity = "compact" | "normal" | "comfortable";
+export interface AutoFormLayout {
+    labelPosition?: "top" | "left";
+    labelAlign?: "left" | "right";
+    labelWidth?: CSSProperties["width"];
+    density?: ComponentDensity;
+    size?: ComponentSize;
+}
+export type FieldName<T> = Extract<keyof T, string>;
+export type Dynamic<V, T> = V | ((values: Readonly<T>) => V);
+export interface Access {
+    roles?: readonly string[];
+    permissions?: readonly string[];
+}
+export interface Option {
+    value: string | number | boolean;
+    label: string;
+    disabled?: boolean;
+    children?: readonly Option[];
+}
+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";
+export interface FieldContext<T extends object> {
+    id: string;
+    value: unknown;
+    values: Readonly<T>;
+    onChange: (value: unknown) => void;
+    disabled: boolean;
+    error?: string;
+}
+export interface FieldBase<T extends object> extends Access {
+    label?: string;
+    lang?: string;
+    type?: FieldType;
+    hidden?: Dynamic<boolean, T>;
+    disabled?: Dynamic<boolean, T>;
+    required?: boolean;
+    placeholder?: string;
+    options?: Dynamic<readonly Option[], T>;
+    multiple?: boolean;
+    span?: number;
+    lineBreak?: boolean;
+    style?: CSSProperties;
+    className?: string;
+    tip?: ReactNode;
+    rules?: readonly ((value: unknown, values: Readonly<T>) => string | undefined | Promise<string | undefined>)[];
+    render?: (context: FieldContext<T>) => ReactNode;
+    component?: string;
+    onChange?: (value: unknown, values: T) => Partial<T> | void;
+    min?: number;
+    max?: number;
+    step?: number;
+    rows?: number;
+    accept?: string;
+    upload?: (files: File[], signal: AbortSignal) => Promise<unknown>;
+    dateValue?: "string" | "timestamp";
+    shortcuts?: readonly {
+        label: string;
+        value: () => unknown;
+    }[];
+    onAction?: (values: Readonly<T>) => void;
+    more?: boolean;
+    match?: "eq" | "in" | "contains" | "between" | "isNull";
+    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;
+};
+export interface StorageAdapter {
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    remove(key: string): void;
+}
+export interface SettingsAdapter {
+    load(key: string): Promise<unknown>;
+    save(key: string, value: unknown): Promise<void>;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./core/types";
+export * from "./core/config";
+export * from "./core/query";
+export * from "./core/AutoConfigProvider";
+export * from "./components/AutoForm";
+export * from "./components/AutoSearchPanel";
+export * from "./components/AutoDialog";
+export * from "./components/AutoTabs";
+export * from "./components/AutoMenu";
+export * from "./components/AutoTable";
+export * from "./components/AutoChat";