@maykonpaulo/maestro-admin 0.3.0 → 0.4.0-next.0

package/README.md

@@ -409,7 +409,7 @@ data, textarea/JSON…).
 
 ## 11. A UI de admin (`maestro-admin`)
 
-A UI (React + Vite + Tailwind) lê `GET /metadata` e monta sozinha: navegação por entidade, tabela
+A UI (React + Vite, CSS puro com temas) lê `GET /metadata` e monta sozinha: navegação por entidade, tabela
 (com busca/ordenação/paginação/filtros vindos do metadata), detalhe, e formulários de criar/editar.
 Ela respeita as **capacidades** (esconde New/Edit/Delete quando desabilitados) e o **RBAC** (403 vira
 erro na tela). **Uma tela, todas as entidades.**
@@ -430,7 +430,7 @@ VITE_MAESTRO_API_URL=http://localhost:3000 \
 
 ```tsx
 import { MaestroAdmin } from '@maykonpaulo/maestro-admin';
-import '@maykonpaulo/maestro-admin/src/styles.css';
+import '@maykonpaulo/maestro-admin/styles.css';
 
 export function AdminPage() {
   return (
@@ -569,7 +569,7 @@ The **generic, metadata-driven admin UI** for Maestro, per [ADR 0008 — Camada
 
 Point it at a running [`@maykonpaulo/maestro-server`](../server) and it reads `GET /metadata` and **auto-builds the whole admin**: a navigation sidebar, a list table, a detail view and create/update forms **for every entity/collection** — no per-entity code. It respects each entity's `capabilities` (a read-only collection shows no New/Edit/Delete) and the server's RBAC (a 403 surfaces as an error, never a broken screen).
 
-Built with **React 19 + Vite + Tailwind**. It ships two ways:
+Built with **React 19 + Vite**, styled with plain CSS custom properties (three built-in themes, light and dark). It ships two ways:
 
 - a **runnable static app** (`vite build`) you configure with an env var, and
 - **exported React components** (`import { MaestroAdmin } from '@maykonpaulo/maestro-admin'`) to embed in your own app.
@@ -591,7 +591,7 @@ VITE_MAESTRO_API_URL=http://localhost:3000 pnpm --filter @maykonpaulo/maestro-ad
 
 ```tsx
 import { MaestroAdmin } from '@maykonpaulo/maestro-admin';
-import '@maykonpaulo/maestro-admin/src/styles.css'; // or include the package in your Tailwind content
+import '@maykonpaulo/maestro-admin/styles.css';
 
 export function AdminPage() {
   return (
@@ -606,24 +606,52 @@ export function AdminPage() {
 
 `headers` may be a function so a fresh auth token is read on every request. Pass a pre-built `client` (a `MaestroClient`) instead of `apiUrl`/`headers` for full control (custom `fetch`, SSR).
 
-### Styling
+The admin fills the box you give it — set a height on the container (`height: 100vh`, a grid cell, whatever). It never styles `html`/`body`.
 
-Tailwind v4. Either import the package's source stylesheet (`@maykonpaulo/maestro-admin/src/styles.css`) or, if you already run Tailwind, add the package to your content so its class names are scanned:
+### Styling and themes
 
-```css
-/* your app.css */
-@import 'tailwindcss';
-@source '../node_modules/@maykonpaulo/maestro-admin/dist';
+One plain-CSS import, no build step and no Tailwind: `@maykonpaulo/maestro-admin/styles.css` (`@maykonpaulo/maestro-admin/src/styles.css` still resolves to the same file). Every colour is a CSS custom property, so nothing depends on your bundler discovering class names.
+
+Three themes ship with the package — `cobalto` (default), `latao` and `teal` — each in light and dark:
+
+```tsx
+<MaestroAdmin apiUrl="…" theme="latao" />
 ```
 
+The header carries a palette picker, a light/dark toggle (system → light → dark) and a density toggle, and remembers what the operator chose. Use the object form for more control:
+
+```tsx
+<MaestroAdmin
+  apiUrl="…"
+  theme={{
+    preset: 'teal',
+    scheme: 'dark',        // 'system' (default) | 'light' | 'dark'
+    density: 'compact',    // 'comfortable' (default) | 'compact'
+    picker: false,         // hide the header controls
+    remember: false,       // don't persist the operator's choices
+    tokens: { '--maestro-brand': '#167B61', '--maestro-shell': '#0B2119' },
+  }}
+/>
+```
+
+`tokens` is applied inline on the admin root, so it wins over the preset in both light and dark. The full token list is at the top of `src/styles.css`; the ones you will reach for most are `--maestro-brand`, `--maestro-shell`, `--maestro-bg`, `--maestro-surface`, `--maestro-border`, `--maestro-fg` and `--maestro-radius`.
+
+### The admin never scrolls sideways
+
+Every screen scrolls vertically only. The hub uses fluid card tracks, the sidebar collapses to icons under 900px, and list tables have fixed column widths with truncation — so an entity with thirty fields does not become thirty columns. Which columns are on screen is the operator's call, from **Columns** in the list toolbar, remembered per entity; the default selection comes from `primaryListFields()` and **Reset columns** hands the decision back to it.
+
 ## Compose your own layout
 
 Beyond the all-in-one `<MaestroAdmin>`, the building blocks are exported so you can assemble a custom shell:
 
-- Components: `EntityList`, `EntityDetail`, `EntityForm`, `Sidebar`, `FieldValue`, `FieldInput`
-- Hooks: `useMetadata`, `useEntityList`, `useEntityRecord`, `useAsync`, and `listFields`/`detailFields`/`formFields`
+- Shell: `Sidebar`, `Header`, `Hub`, `CommandPalette` (+ `entityCommands`), `MaestroThemeProvider`, `useTheme`
+- Screens: `EntityList`, `EntityDetail`, `EntityForm`, `FieldValue`, `FieldInput`
+- Primitives: `Button`, `IconButton`, `Badge`, `Spinner`, `EmptyState`, `ErrorBanner`, `Toast`, `Icon`, `entityIcon`
+- Hooks: `useMetadata`, `useEntityList`, `useEntityRecord`, `useAsync`, `useColumnPrefs`, `useRecents`, and `listFields`/`detailFields`/`formFields`
 - Client: `MaestroClient`, `MaestroApiError`, `AdminClientProvider`, `useClient`
 
+Composing your own shell means owning the token root too: wrap it in `<MaestroThemeProvider className="mst-root">`, which is what paints `data-maestro-theme`/`-scheme`/`-density`.
+
 All of them talk to the server through a single `MaestroClient` provided via `AdminClientProvider`.
 
 ## What it renders from metadata

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import { ReactNode, ReactElement, ButtonHTMLAttributes } from 'react';
 
 type FieldType = 'string' | 'text' | 'integer' | 'float' | 'boolean' | 'date' | 'datetime' | 'enum' | 'json' | 'relation' | 'uuid' | 'email' | (string & {});
 interface EnumOption {
@@ -186,6 +187,34 @@ interface AdminStrings {
     recents: string;
     menus: string;
     noMenuResults: string;
+    hub: string;
+    breadcrumb: string;
+    search: string;
+    commandKey: string;
+    commandPalette: string;
+    palettePlaceholder: string;
+    goTo: string;
+    onThisScreen: string;
+    appearance: string;
+    palette: string;
+    density: string;
+    colorScheme: string;
+    schemeSystem: string;
+    schemeLight: string;
+    schemeDark: string;
+    entities: string;
+    hubMeta: (entities: number, sources: number) => string;
+    otherEntities: string;
+    noEntities: string;
+    noEntitiesHint: string;
+    fieldCount: (count: number) => string;
+    capRead: string;
+    capCreate: string;
+    capUpdate: string;
+    capDelete: string;
+    columns: string;
+    columnsCount: (visible: number, total: number) => string;
+    resetColumns: string;
 }
 declare function stringsFor(locale: AdminLocale): AdminStrings;
 declare const I18nProvider: react.Provider<AdminStrings>;
@@ -217,6 +246,64 @@ interface AdminLabels {
 /** 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;
 
+/** Built-in palettes. Each ships a light and a dark set of the same tokens. */
+type MaestroThemeName = 'cobalto' | 'latao' | 'teal';
+/** `system` follows the OS `prefers-color-scheme`; the other two force the decision. */
+type MaestroScheme = 'system' | 'light' | 'dark';
+/** Table row height. `compact` fits roughly 40% more rows on a screen and changes nothing else. */
+type MaestroDensity = 'comfortable' | 'compact';
+interface MaestroThemeOption {
+    id: MaestroThemeName;
+    label: string;
+    /** Light-mode brand colour — what the picker shows as the palette's dot. */
+    swatch: string;
+}
+declare const MAESTRO_THEMES: readonly MaestroThemeOption[];
+interface MaestroThemeConfig {
+    /** Palette to start on. Defaults to `cobalto`. */
+    preset?: MaestroThemeName;
+    /** Light/dark decision to start on. Defaults to `system`. */
+    scheme?: MaestroScheme;
+    /** Row density to start on. Defaults to `comfortable`. */
+    density?: MaestroDensity;
+    /**
+     * Token overrides applied inline on the admin root, so they win over the preset in both schemes:
+     * `{ '--maestro-brand': '#167B61' }`. Use this to dress the admin in your own brand.
+     */
+    tokens?: Record<string, string>;
+    /** Show the palette / light-dark / density controls in the header. Defaults to `true`. */
+    picker?: boolean;
+    /** Remember the operator's choices in `localStorage`. Defaults to `true`. */
+    remember?: boolean;
+}
+/** `theme="cobalto"` is shorthand for `theme={{ preset: 'cobalto' }}`. */
+type MaestroThemeInput = MaestroThemeName | MaestroThemeConfig;
+interface MaestroThemeState {
+    preset: MaestroThemeName;
+    scheme: MaestroScheme;
+    density: MaestroDensity;
+    picker: boolean;
+    setPreset: (preset: MaestroThemeName) => void;
+    setScheme: (scheme: MaestroScheme) => void;
+    setDensity: (density: MaestroDensity) => void;
+}
+/** The active appearance and its setters. Safe outside a provider — falls back to the defaults. */
+declare function useTheme(): MaestroThemeState;
+/**
+ * Owns the appearance state and paints the root element that carries the tokens. Everything below it
+ * reads colours from CSS custom properties, so a theme switch is one attribute change — no re-render
+ * of the tree's styles, no class swapping.
+ *
+ * The props are the *initial* values: once the operator picks a palette from the header it is
+ * remembered (unless `remember: false`), and the stored choice wins on the next mount.
+ */
+declare function MaestroThemeProvider({ theme, className, children, rootRef, }: {
+    theme?: MaestroThemeInput;
+    className?: string;
+    children: ReactNode;
+    rootRef?: (node: HTMLDivElement | null) => void;
+}): react.JSX.Element;
+
 interface MaestroAdminProps {
     /** Base URL of the running maestro-server. Ignored when `client` is given. */
     apiUrl?: string;
@@ -230,17 +317,29 @@ interface MaestroAdminProps {
     locale?: AdminLocale;
     /** Label rewrites (localization/humanization) applied over the served metadata. */
     labels?: AdminLabels;
+    /**
+     * Appearance: `"cobalto" | "latao" | "teal"`, or an object to also set the light/dark scheme, the
+     * row density, whether the header shows the pickers, and per-token overrides for your own brand.
+     */
+    theme?: MaestroThemeInput;
 }
 /**
  * The whole metadata-driven admin in one component. Point it at a running maestro-server and it reads
  * `GET /metadata` and auto-builds navigation, tables, detail views and create/update forms for every
  * entity — respecting each entity's capabilities and the server's RBAC. No per-entity code.
+ *
+ * Styles ship separately so the host app controls bundling:
+ * `import '@maykonpaulo/maestro-admin/styles.css'`.
  */
 declare function MaestroAdmin(props: MaestroAdminProps): react.JSX.Element;
 
 declare const AdminClientProvider: react.Provider<MaestroClient | null>;
 /** Returns the `MaestroClient` provided at the root of the admin. Throws if used outside the provider. */
 declare function useClient(): MaestroClient;
+/** All entities from the loaded metadata — lets deep components (relation chips) resolve a target entity. */
+declare function useEntities(): EntityMetadata[];
+declare function useEntity(entityId: string | undefined): EntityMetadata | undefined;
+declare function useAdminRoot(): HTMLElement | null;
 
 interface AsyncState<T> {
     data: T | undefined;
@@ -302,6 +401,27 @@ declare function useRecents(scope?: string): {
     push: (entityId: string) => void;
 };
 
+interface ColumnPrefs {
+    /** The fields to render, in metadata order. */
+    columns: FieldMetadata[];
+    /** Every field that *could* be a column, for the picker. */
+    available: FieldMetadata[];
+    visible: (name: string) => boolean;
+    toggle: (name: string) => void;
+    reset: () => void;
+    /** True when the operator has overridden the metadata's default selection. */
+    customized: boolean;
+}
+/**
+ * Which columns an entity's table shows, remembered per entity.
+ *
+ * The admin never scrolls sideways, so an entity with thirty fields cannot simply render thirty
+ * columns — something has to choose. The default choice is `primaryListFields`, which reads the
+ * metadata; this hook lets the operator override it for the entities they actually work in, and
+ * `reset` hands the decision back to the metadata.
+ */
+declare function useColumnPrefs(entity: EntityMetadata, max?: number): ColumnPrefs;
+
 declare function EntityList({ entity, onOpen, onCreate, onEdit, onClone, onNavigate, initialFilters, }: {
     entity: EntityMetadata;
     onOpen: (id: string) => void;
@@ -332,7 +452,7 @@ declare function EntityForm({ entity, mode, id, cloneFromId, onCancel, onSaved,
     onSaved: (record: Record_) => void;
 }): react.JSX.Element;
 
-declare function Sidebar({ entities, activeId, onSelect, title, labels, recents, }: {
+declare function Sidebar({ entities, activeId, onSelect, title, labels, recents, onHome, homeActive, }: {
     entities: EntityMetadata[];
     activeId: string | undefined;
     onSelect: (entityId: string) => void;
@@ -341,11 +461,169 @@ declare function Sidebar({ entities, activeId, onSelect, title, labels, recents,
     labels?: AdminLabels;
     /** Recently-visited entity ids, most recent first. */
     recents?: string[];
+    /** Opens the hub. Omit to hide the hub entry (standalone/embedded use). */
+    onHome?: () => void;
+    homeActive?: boolean;
+}): react.JSX.Element;
+
+/**
+ * The admin's icon set, inline.
+ *
+ * Twenty-odd 24×24 stroke glyphs are not worth a runtime dependency: `@maykonpaulo/maestro-admin`
+ * ships with `dependencies: {}` and this file is why. Every glyph is drawn on the same grid with the
+ * same stroke weight, and takes its colour from `currentColor`.
+ */
+declare const PATHS: {
+    readonly hub: react.JSX.Element;
+    readonly baton: react.JSX.Element;
+    readonly search: react.JSX.Element;
+    readonly chevronRight: react.JSX.Element;
+    readonly chevronLeft: react.JSX.Element;
+    readonly chevronsLeft: react.JSX.Element;
+    readonly chevronsRight: react.JSX.Element;
+    readonly plus: react.JSX.Element;
+    readonly close: react.JSX.Element;
+    readonly check: react.JSX.Element;
+    readonly filter: react.JSX.Element;
+    readonly download: react.JSX.Element;
+    readonly columns: react.JSX.Element;
+    readonly rows: react.JSX.Element;
+    readonly sun: react.JSX.Element;
+    readonly moon: react.JSX.Element;
+    readonly swatch: react.JSX.Element;
+    readonly dots: react.JSX.Element;
+    readonly trash: react.JSX.Element;
+    readonly pencil: react.JSX.Element;
+    readonly eye: react.JSX.Element;
+    readonly copy: react.JSX.Element;
+    readonly clone: react.JSX.Element;
+    readonly arrowUpRight: react.JSX.Element;
+    readonly arrowLeft: react.JSX.Element;
+    readonly sort: react.JSX.Element;
+    readonly sortAsc: react.JSX.Element;
+    readonly sortDesc: react.JSX.Element;
+    readonly database: react.JSX.Element;
+    readonly table: react.JSX.Element;
+    readonly users: react.JSX.Element;
+    readonly box: react.JSX.Element;
+    readonly receipt: react.JSX.Element;
+    readonly key: react.JSX.Element;
+    readonly shield: react.JSX.Element;
+    readonly activity: react.JSX.Element;
+    readonly tag: react.JSX.Element;
+    readonly map: react.JSX.Element;
+    readonly calendar: react.JSX.Element;
+    readonly mail: react.JSX.Element;
+    readonly file: react.JSX.Element;
+    readonly alert: react.JSX.Element;
+};
+type IconName = keyof typeof PATHS;
+declare function Icon({ name, size, className, title, }: {
+    name: IconName;
+    size?: number;
+    className?: string;
+    title?: string;
+}): ReactElement;
+/**
+ * A glyph for an entity, guessed from its names. A metadata-driven admin has no idea what a
+ * collection *means*, so this is deliberately a hint and not a promise: anything unrecognised gets
+ * the neutral table glyph, which is always a defensible answer.
+ */
+declare function entityIcon(entity: EntityMetadata): IconName;
+
+interface Crumb {
+    label: string;
+    icon?: IconName;
+    /** Omit on the last crumb — the current place is not a link. */
+    onClick?: () => void;
+}
+/**
+ * The bar above the content: where you are (breadcrumbs), how to get anywhere (⌘K), and how the admin
+ * looks (palette, light/dark, density). The appearance controls live here rather than in a settings
+ * page because they are the operator's, changed mid-task and never worth a navigation.
+ */
+declare function Header({ crumbs, onOpenPalette }: {
+    crumbs: Crumb[];
+    onOpenPalette: () => void;
+}): react.JSX.Element;
+
+/**
+ * The landing screen: every entity the server serves, in its sidebar folder, with what you can do to
+ * it and where it actually lives. That last part is the whole point — Maestro speaks a dozen
+ * providers, so "which database is this collection in" is a real question with a real answer, and no
+ * other admin can show it.
+ *
+ * Record counts are deliberately absent: metadata does not carry them, and one `count` request per
+ * entity would turn opening the admin into thirty round-trips. The count you get is the real one, in
+ * the list header, once you open an entity.
+ */
+declare function Hub({ entities, labels, onOpen, }: {
+    entities: EntityMetadata[];
+    labels?: AdminLabels;
+    onOpen: (entityId: string) => void;
+}): react.JSX.Element;
+
+interface PaletteCommand {
+    id: string;
+    label: string;
+    icon?: IconName;
+    /** Right-aligned affordance: a shortcut, or the folder an entity belongs to. */
+    hint?: string;
+    /** Extra words matched by the search but never displayed (table name, singular label). */
+    keywords?: string;
+    run: () => void;
+}
+interface PaletteSection {
+    id: string;
+    label: string;
+    commands: PaletteCommand[];
+}
+/** Turns the entity list into palette commands — the navigation half of the palette. */
+declare function entityCommands(entities: EntityMetadata[], groupOf: Map<string, string>, onSelect: (entityId: string) => void): PaletteCommand[];
+/**
+ * ⌘K. Everything reachable in the admin — every entity, plus whatever the current screen can do —
+ * behind one accent-insensitive search, driven entirely from the keyboard.
+ */
+declare function CommandPalette({ sections, onClose }: {
+    sections: PaletteSection[];
+    onClose: () => void;
+}): react.ReactPortal;
+
+type Variant = 'primary' | 'secondary' | 'danger' | 'ghost';
+declare function Button({ variant, icon, className, children, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & {
+    variant?: Variant;
+    icon?: IconName;
+}): react.JSX.Element;
+/** A square, label-less button. `label` is required — it is the accessible name and the tooltip. */
+declare function IconButton({ icon, label, className, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & {
+    icon: IconName;
+    label: string;
+}): react.JSX.Element;
+type BadgeTone = 'neutral' | 'brand' | 'ok' | 'warn' | 'danger';
+declare function Badge({ children, tone, dot }: {
+    children: ReactNode;
+    tone?: BadgeTone;
+    dot?: boolean;
+}): react.JSX.Element;
+declare function Spinner({ label }: {
+    label?: string;
+}): react.JSX.Element;
+declare function EmptyState({ title, hint }: {
+    title: string;
+    hint?: string;
+}): react.JSX.Element;
+declare function ErrorBanner({ error }: {
+    error: Error;
+}): react.JSX.Element;
+/** The transient confirmation strip ("Copied!"). Callers own the timer; this only draws it. */
+declare function Toast({ children }: {
+    children: ReactNode;
 }): react.JSX.Element;
 
 /**
  * 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.
+ * `compact` is the table-cell mode: the cell itself truncates, so this only has to avoid rendering
+ * anything that would force the row taller.
  */
 declare function FieldValue({ field, value, compact }: {
     field: FieldMetadata;
@@ -386,4 +664,4 @@ declare function JsonInput({ field, value, onChange, disabled, }: {
     disabled?: boolean;
 }): react.JSX.Element;
 
-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, JsonInput, type ListQuery, type ListResult, MaestroAdmin, type MaestroAdminProps, MaestroApiError, MaestroClient, type MaestroClientConfig, type MaestroMetadata, type MenuGroup, ObjectValue, Sidebar, type SidebarMenu, applyLabels, buildMenu, detailFields, formFields, listFields, primaryListFields, stringsFor, useAsync, useClient, useEntityList, useEntityRecord, useMetadata, useRecents, useT };
+export { AdminClientProvider, type AdminLabels, type AdminLocale, type AdminStrings, type AsyncState, Badge, Button, type ColumnPrefs, CommandPalette, type Crumb, EmptyState, type EntityCapabilities, EntityDetail, EntityForm, type EntityLabelOverride, EntityList, type EntityMetadata, ErrorBanner, FieldInput, type FieldMetadata, FieldValue, type FilterInput, Header, Hub, I18nProvider, Icon, IconButton, type IconName, JsonInput, type ListQuery, type ListResult, MAESTRO_THEMES, MaestroAdmin, type MaestroAdminProps, MaestroApiError, MaestroClient, type MaestroClientConfig, type MaestroDensity, type MaestroMetadata, type MaestroScheme, type MaestroThemeConfig, type MaestroThemeInput, type MaestroThemeName, type MaestroThemeOption, MaestroThemeProvider, type MaestroThemeState, type MenuGroup, ObjectValue, type PaletteCommand, type PaletteSection, Sidebar, type SidebarMenu, Spinner, Toast, applyLabels, buildMenu, detailFields, entityCommands, entityIcon, formFields, listFields, primaryListFields, stringsFor, useAdminRoot, useAsync, useClient, useColumnPrefs, useEntities, useEntity, useEntityList, useEntityRecord, useMetadata, useRecents, useT, useTheme };