@maykonpaulo/maestro-admin 0.1.2 → 0.2.0-next.1

package/dist/index.d.ts

@@ -86,12 +86,19 @@ interface SortInput {
     field: string;
     direction: 'asc' | 'desc';
 }
+/** One filter clause, serialized to the server's `filter=field:operator:value` query param. */
+interface FilterInput {
+    field: string;
+    operator: 'equals' | 'notEquals' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'notIn' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'isNull' | 'isNotNull' | 'isTrue' | 'isFalse';
+    value?: string;
+}
 interface ListQuery {
     page?: number;
     pageSize?: number;
     search?: string;
     searchFields?: string[];
     sort?: SortInput[];
+    filters?: FilterInput[];
 }
 
 interface MaestroClientConfig {
@@ -128,6 +135,82 @@ declare class MaestroClient {
     remove(entityId: string, id: string): Promise<void>;
 }
 
+type AdminLocale = 'en' | 'pt-BR';
+/**
+ * Every user-facing string the admin chrome renders. Entity/field labels are NOT here — those come
+ * from the server metadata (optionally rewritten via `AdminLabels`); this dictionary covers only the
+ * UI around them (buttons, menus, pagination, confirmations).
+ */
+interface AdminStrings {
+    loading: string;
+    loadingMetadata: string;
+    records: (total: number) => string;
+    searchPlaceholder: (plural: string) => string;
+    newRecord: string;
+    view: string;
+    edit: string;
+    clone: string;
+    remove: string;
+    copyId: string;
+    copyObject: string;
+    copyValue: string;
+    copied: string;
+    addToFilter: string;
+    openRelated: (label: string) => string;
+    filters: string;
+    clearFilters: string;
+    actions: string;
+    noRecords: string;
+    tryDifferentSearch: string;
+    deleteConfirm: (singular: string) => string;
+    page: (page: number, total: number) => string;
+    previous: string;
+    next: string;
+    cancel: string;
+    save: string;
+    saving: string;
+    create: string;
+    newTitle: (singular: string) => string;
+    editTitle: (singular: string) => string;
+    cloneTitle: (singular: string) => string;
+    entitiesFooter: (count: number) => string;
+    yes: string;
+    no: string;
+    searchMenu: string;
+    recents: string;
+    menus: string;
+    noMenuResults: string;
+}
+declare function stringsFor(locale: AdminLocale): AdminStrings;
+declare const I18nProvider: react.Provider<AdminStrings>;
+/** The active UI-string dictionary (set by `<MaestroAdmin locale>`; defaults to English). */
+declare function useT(): AdminStrings;
+
+interface EntityLabelOverride {
+    /** Singular label ("Usuário"). */
+    singular?: string;
+    /** Plural label ("Usuários") — also the sidebar entry. */
+    plural?: string;
+    /** Sidebar folder this entity belongs to (display name). Wins over heuristic prefix grouping. */
+    group?: string;
+    /** Field labels for this entity only, by field name. Wins over the global `fields` map. */
+    fields?: Record<string, string>;
+}
+/**
+ * Presentation-layer label rewrites, applied on top of the metadata the server serves. This is how a
+ * deployment localizes or humanizes auto-introspected names ("recoveryactions" → "Ações de
+ * Recuperação") without touching the engine: keys match either the entity `id` or its source `table`.
+ */
+interface AdminLabels {
+    entities?: Record<string, EntityLabelOverride>;
+    /** Global field labels by field name (`createdAt` → "Criado em"), for every entity. */
+    fields?: Record<string, string>;
+    /** Display names for heuristic sidebar folders, by shared table-name prefix (`recovery` → "Recuperação"). */
+    groups?: Record<string, string>;
+}
+/** Returns a copy of `metadata` with every label override applied. No-op when `labels` is empty. */
+declare function applyLabels(metadata: MaestroMetadata, labels: AdminLabels | undefined): MaestroMetadata;
+
 interface MaestroAdminProps {
     /** Base URL of the running maestro-server. Ignored when `client` is given. */
     apiUrl?: string;
@@ -137,6 +220,10 @@ interface MaestroAdminProps {
     client?: MaestroClient;
     /** Sidebar title. Defaults to "Maestro Admin". */
     title?: string;
+    /** UI-chrome language (buttons, menus, pagination). Defaults to `en`. */
+    locale?: AdminLocale;
+    /** Label rewrites (localization/humanization) applied over the served metadata. */
+    labels?: AdminLabels;
 }
 /**
  * The whole metadata-driven admin in one component. Point it at a running maestro-server and it reads
@@ -165,44 +252,99 @@ declare function useEntityList(entityId: string, query: ListQuery): AsyncState<L
 declare function useEntityRecord(entityId: string, id: string | undefined): AsyncState<globalThis.Record<string, unknown>>;
 /** Fields shown in the list table, ordered, honoring per-field list visibility. */
 declare function listFields(entity: EntityMetadata): FieldMetadata[];
+/**
+ * The "principal" columns for an entity's table: instead of dumping every field, picks up to `max`
+ * of the most identifying ones — the display field first, then searchable/required texts, enums,
+ * relations, status booleans and dates — and drops blobs (`json`/`array`/`text`), sensitive values
+ * and the primary key. Everything remains visible in the detail view. When any field carries an
+ * explicit `list.order`/`list.width` (a curated schema), the curator's selection is honored as-is.
+ */
+declare function primaryListFields(entity: EntityMetadata, max?: number): FieldMetadata[];
 /** Fields shown in the detail view, ordered. */
 declare function detailFields(entity: EntityMetadata): FieldMetadata[];
 /** Fields editable in the create/update form, ordered, per mode. */
 declare function formFields(entity: EntityMetadata, mode: 'create' | 'edit'): FieldMetadata[];
 
-declare function EntityList({ entity, onOpen, onCreate, onEdit, }: {
+interface MenuGroup {
+    /** Stable key: the explicit group name, or the heuristic table-name prefix. */
+    id: string;
+    label: string;
+    entities: EntityMetadata[];
+}
+interface SidebarMenu {
+    groups: MenuGroup[];
+    /** Entities that belong to no group — rendered flat after the folders. */
+    ungrouped: EntityMetadata[];
+}
+/**
+ * Builds the sidebar menu structure: explicit groups first (an entity override's `group` in
+ * `AdminLabels` always wins), then heuristic clustering of what's left — collections sharing a
+ * table-name prefix (`recoveryactions`, `recoveryscores`, … → "Recovery") become a folder, since a
+ * shared prefix is how schemaless databases usually encode the module a collection belongs to.
+ * Heuristic folder names can be localized via `labels.groups` (prefix → display name). Everything
+ * else stays flat. Groups and their entities are sorted by label.
+ */
+declare function buildMenu(entities: EntityMetadata[], labels?: AdminLabels): SidebarMenu;
+
+/**
+ * Recently-visited entity ids, most recent first, persisted in `localStorage` so they survive
+ * reloads. `push` moves (or inserts) an id to the front, capped at 8. Pass a distinct `scope` (e.g.
+ * the API URL) when one browser origin hosts admins for several servers.
+ */
+declare function useRecents(scope?: string): {
+    recents: string[];
+    push: (entityId: string) => void;
+};
+
+declare function EntityList({ entity, onOpen, onCreate, onEdit, onClone, onNavigate, initialFilters, }: {
     entity: EntityMetadata;
     onOpen: (id: string) => void;
     onCreate: () => void;
     onEdit: (id: string) => void;
+    onClone: (id: string) => void;
+    onNavigate: (entityId: string, id: string) => void;
+    initialFilters?: FilterInput[];
 }): react.JSX.Element;
 
-declare function EntityDetail({ entity, id, onBack, onEdit, }: {
+declare function EntityDetail({ entity, id, onBack, onEdit, onClone, onDeleted, onNavigate, }: {
     entity: EntityMetadata;
     id: string;
     onBack: () => void;
     onEdit: () => void;
+    onClone: () => void;
+    onDeleted: () => void;
+    onNavigate: (entityId: string, id: string) => void;
 }): react.JSX.Element;
 
-declare function EntityForm({ entity, mode, id, onCancel, onSaved, }: {
+declare function EntityForm({ entity, mode, id, cloneFromId, onCancel, onSaved, }: {
     entity: EntityMetadata;
     mode: 'create' | 'edit';
     id?: string;
+    /** In `create` mode, prefills the form from this record (minus the primary key and non-cloneable fields). */
+    cloneFromId?: string;
     onCancel: () => void;
     onSaved: (record: Record_) => void;
 }): react.JSX.Element;
 
-declare function Sidebar({ entities, activeId, onSelect, title, }: {
+declare function Sidebar({ entities, activeId, onSelect, title, labels, recents, }: {
     entities: EntityMetadata[];
     activeId: string | undefined;
     onSelect: (entityId: string) => void;
     title: string;
+    /** Same object given to `<MaestroAdmin labels>` — supplies folder assignments and folder names. */
+    labels?: AdminLabels;
+    /** Recently-visited entity ids, most recent first. */
+    recents?: string[];
 }): react.JSX.Element;
 
-/** Renders a single record value read-only, shaped by the field's type (for tables and detail views). */
-declare function FieldValue({ field, value }: {
+/**
+ * Renders a single record value read-only, shaped by the field's type (for tables and detail views).
+ * `compact` is the table-cell mode: long text truncates instead of stretching the row.
+ */
+declare function FieldValue({ field, value, compact }: {
     field: FieldMetadata;
     value: unknown;
+    compact?: boolean;
 }): react.JSX.Element;
 
 /**
@@ -217,4 +359,4 @@ declare function FieldInput({ field, value, onChange, disabled, }: {
     disabled?: boolean;
 }): react.JSX.Element;
 
-export { AdminClientProvider, type AsyncState, type EntityCapabilities, EntityDetail, EntityForm, EntityList, type EntityMetadata, FieldInput, type FieldMetadata, FieldValue, type ListQuery, type ListResult, MaestroAdmin, type MaestroAdminProps, MaestroApiError, MaestroClient, type MaestroClientConfig, type MaestroMetadata, Sidebar, detailFields, formFields, listFields, useAsync, useClient, useEntityList, useEntityRecord, useMetadata };
+export { AdminClientProvider, type AdminLabels, type AdminLocale, type AdminStrings, type AsyncState, type EntityCapabilities, EntityDetail, EntityForm, type EntityLabelOverride, EntityList, type EntityMetadata, FieldInput, type FieldMetadata, FieldValue, type FilterInput, I18nProvider, type ListQuery, type ListResult, MaestroAdmin, type MaestroAdminProps, MaestroApiError, MaestroClient, type MaestroClientConfig, type MaestroMetadata, type MenuGroup, Sidebar, type SidebarMenu, applyLabels, buildMenu, detailFields, formFields, listFields, primaryListFields, stringsFor, useAsync, useClient, useEntityList, useEntityRecord, useMetadata, useRecents, useT };