shutro-erp 0.3.5 → 0.3.7

package/dist/ui/api.d.ts

@@ -73,6 +73,8 @@ export interface CurrentUser {
     readonly twoFactorEnabled: boolean;
     readonly administrator: boolean;
     readonly administratorNeedsSecondFactor: boolean;
+    /** May turn on Developer mode (RFC 0031 §3.1); older servers send none. */
+    readonly developer?: boolean;
     /** The policy requires two-factor sign-in of everyone and it is not on (RFC 0019 §3.5); older servers send none. */
     readonly twoFactorSetupRequired?: boolean;
     /** The user's photo version, or null (older servers send none). */

package/dist/ui/app.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The Kosh back-office app (RFC 0007): TanStack Router routes from apps, menus and actions, TanStack Query for
+ * server state, the shell (launcher, menus filtered by the server, company, language, theme), and the view
+ * renderers from the registry. Search state lives in the URL (`?view=kanban&q=...`), so deep links and the back
+ * button work.
+ *
+ * Routes: `/login`, `/` (launcher), `/:app` (first menu entry), `/:app/a/:action` (list / kanban),
+ * `/:app/a/:action/:id` (form; `new` for a new record).
+ */
 import { type ReactElement, type ReactNode } from 'react';
 import { type KoshApi } from './api.js';
 import type { Registry } from './registry.js';

package/dist/ui/app.js

@@ -12,12 +12,13 @@ import { compileSearch, decodeSearch, encodeSearch } from '../search/index.js';
 import { onlineManager, QueryClient, QueryClientProvider, useQuery, useQueryClient, } from '@tanstack/react-query';
 import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
 import { createRootRoute, createRoute, createRouter, Link, Navigate, Outlet, RouterProvider, useNavigate, useParams, useSearch, } from '@tanstack/react-router';
-import { CalendarDays, ChartColumn, ChartGantt, ChevronDown, ChevronRight, ChevronsUpDown, Columns3, Grid2x2, House, Languages, LayoutDashboard, List, LogOut, Map as MapIcon, Monitor, Moon, Network, PanelLeft, Plus, Search, Sheet, Sun, Table2, } from 'lucide-react';
+import { Building2, CalendarDays, ChartColumn, ChartGantt, ChevronDown, ChevronRight, ChevronsUpDown, Columns3, Grid2x2, House, Languages, LayoutDashboard, List, LogOut, Map as MapIcon, Monitor, Moon, Network, PanelLeft, Plus, Search, Sheet, Sun, Table2, } from 'lucide-react';
 import { Direction } from 'radix-ui';
 import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
 import { I18nextProvider, useTranslation } from 'react-i18next';
 import { ApiError } from './api.js';
 import { Avatar, imageUrl } from './components/Avatar.js';
+import { Explain } from './components/Explain.js';
 import { Alert, Button, Menu, MenuCheckboxItem, MenuContent, MenuItem, MenuLabel, MenuSeparator, MenuTrigger, Spinner, } from './components/primitives.js';
 import { KoshProvider, useKosh } from './context.js';
 import { DesignProvider } from './design.js';
@@ -139,6 +140,7 @@ function LanguageMenu() {
 function CompanyBlock({ me, company, collapsed, onChange, }) {
     const { t } = useTranslation();
     const { api } = useServices();
+    const navigate = useNavigate();
     const names = useQuery({
         queryKey: ['names', 'res.company', me.companies],
         queryFn: () => api.names('res.company', { ids: me.companies }),
@@ -147,26 +149,37 @@ function CompanyBlock({ me, company, collapsed, onChange, }) {
     const name = names.data?.find((c) => c.id === company)?.displayName ?? t('app.name');
     // The company's logo, else its initial.
     const badge = (_jsx(Avatar, { name: name.slice(0, 1), src: imageUrl('company', company, me.logos?.[String(company)]), shape: "square", className: "font-semibold" }));
-    if (collapsed)
-        return _jsx("span", { title: name, children: badge });
-    if (me.companies.length < 2)
-        return (_jsxs("div", { className: "flex items-center gap-2.5 px-1 py-1", children: [badge, _jsx("span", { className: "truncate text-sm font-semibold", children: name })] }));
-    // Several companies: a switcher (also in the palette: "Switch to …").
-    return (_jsxs(Menu, { children: [_jsx(MenuTrigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": t('shell.switchCompany', { name }), className: "flex w-full items-center gap-2.5 rounded-md px-1 py-1 text-start hover:bg-muted", children: [badge, _jsx("span", { className: "min-w-0 flex-1 truncate text-sm font-semibold", children: name }), _jsx(ChevronsUpDown, { className: "size-4 shrink-0 text-muted-foreground", "aria-hidden": true })] }) }), _jsxs(MenuContent, { align: "start", className: "w-64", children: [_jsx(MenuLabel, { children: t('shell.company') }), (names.data ?? []).map((c) => (_jsx(MenuCheckboxItem, { checked: c.id === company, onCheckedChange: () => {
+    const several = me.companies.length > 1;
+    // Nothing to switch to and nothing to manage: the company's name only.
+    if (!several && !me.administrator)
+        return collapsed ? (_jsx("span", { title: name, children: badge })) : (_jsxs("div", { className: "flex items-center gap-2.5 px-1 py-1", children: [badge, _jsx("span", { className: "truncate text-sm font-semibold", children: name })] }));
+    // A menu: the companies to switch to (also in the palette: "Switch to …"), and for administrators the Companies
+    // page, where companies are added — so a one-company installation still shows where multi-company starts.
+    return (_jsxs(Menu, { children: [_jsx(MenuTrigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": t(several ? 'shell.switchCompany' : 'shell.companyMenu', { name }), title: collapsed ? name : undefined, className: collapsed
+                        ? 'rounded-md hover:bg-muted'
+                        : 'flex w-full items-center gap-2.5 rounded-md px-1 py-1 text-start hover:bg-muted', children: [badge, collapsed ? null : (_jsxs(_Fragment, { children: [_jsx("span", { className: "min-w-0 flex-1 truncate text-sm font-semibold", children: name }), _jsx(ChevronsUpDown, { className: "size-4 shrink-0 text-muted-foreground", "aria-hidden": true })] }))] }) }), _jsxs(MenuContent, { align: "start", className: "w-64", children: [_jsx(MenuLabel, { children: t('shell.company') }), (names.data ?? []).map((c) => (_jsx(MenuCheckboxItem, { checked: c.id === company, onCheckedChange: () => {
                             if (c.id !== company)
                                 onChange(c.id);
-                        }, children: _jsxs("span", { className: "flex items-center gap-2", children: [_jsx("span", { "aria-hidden": true, className: "grid size-5 place-items-center rounded bg-muted text-[10px] font-semibold", children: c.displayName.slice(0, 1).toUpperCase() }), c.displayName] }) }, c.id)))] })] }));
+                        }, children: _jsxs("span", { className: "flex items-center gap-2", children: [_jsx("span", { "aria-hidden": true, className: "grid size-5 place-items-center rounded bg-muted text-[10px] font-semibold", children: c.displayName.slice(0, 1).toUpperCase() }), c.displayName] }) }, c.id))), me.administrator ? (_jsxs(_Fragment, { children: [_jsx(MenuSeparator, {}), _jsxs(MenuItem, { onSelect: () => void navigate({
+                                    to: '/$app/a/$action',
+                                    params: { app: 'settings', action: 'settings.action_companies' },
+                                }), children: [_jsx(Building2, { "aria-hidden": true }), t(several ? 'shell.manageCompanies' : 'shell.addCompany')] })] })) : null] })] }));
 }
 function UserMenu({ user, collapsed, corner, }) {
     const { t } = useTranslation();
     const { api, registry, persister, lang, setLang } = useServices();
-    const { theme, setTheme, density, setDensity } = useKosh();
+    const { theme, setTheme, density, setDensity, developer, canDevelop, setDeveloper } = useKosh();
     const queryClient = useQueryClient();
     const navigate = useNavigate();
-    return (_jsxs(Menu, { children: [_jsx(MenuTrigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": user.name, "data-kosh-account": corner === undefined ? 'sidebar' : 'corner', className: cn('flex min-w-0 items-center gap-2 rounded-md px-1.5 py-1.5 text-sm hover:bg-muted', corner === undefined ? 'w-full' : 'rounded-full border bg-surface pe-3', collapsed && 'justify-center'), children: [_jsx(Avatar, { name: user.name, src: imageUrl('user', user.id, user.avatar) }), collapsed ? null : _jsx("span", { className: "truncate", children: user.name }), corner === undefined ? null : (_jsx(ChevronDown, { className: "size-3.5 text-muted-foreground", "aria-hidden": true }))] }) }), _jsxs(MenuContent, { align: corner === undefined ? 'start' : 'end', side: corner === undefined ? 'top' : 'bottom', className: corner === undefined ? undefined : 'max-h-[80vh] w-64 overflow-y-auto', children: [_jsxs(MenuLabel, { children: [user.name, _jsx("span", { className: "block text-xs font-normal text-muted-foreground", children: user.login })] }), registry.userPages().map((p) => (_jsx(MenuItem, { onSelect: () => void navigate({ to: '/me/$page', params: { page: p.name } }), children: t(p.label) }, p.name))), corner === undefined ? null : (_jsxs(_Fragment, { children: [corner.companies.length < 2 ? null : (_jsxs(_Fragment, { children: [_jsx(MenuSeparator, {}), _jsx(MenuLabel, { children: t('shell.company') }), corner.companies.map((c) => (_jsx(MenuCheckboxItem, { checked: c.id === corner.current, onCheckedChange: () => {
-                                            if (c.id !== corner.current)
-                                                corner.onSwitch(c.id);
-                                        }, children: c.name }, c.id)))] })), _jsx(MenuSeparator, {}), _jsx(MenuLabel, { children: t('shell.language') }), LANGUAGES.map((l) => (_jsx(MenuCheckboxItem, { checked: lang === l.code, onCheckedChange: () => setLang(l.code), children: _jsx("span", { lang: l.code.replace('_', '-'), children: l.name }) }, l.code))), _jsx(MenuSeparator, {}), _jsx(MenuLabel, { children: t('shell.theme') }), ['light', 'dark', 'system'].map((choice) => (_jsx(MenuCheckboxItem, { checked: theme === choice, onCheckedChange: () => setTheme(choice), children: t(`shell.${choice}`) }, choice))), _jsx(MenuLabel, { children: t('shell.density') }), ['comfortable', 'compact'].map((choice) => (_jsx(MenuCheckboxItem, { checked: density === choice, onCheckedChange: () => setDensity(choice), children: t(`views.${choice}`) }, choice)))] })), _jsx(MenuSeparator, {}), _jsxs(MenuItem, { onSelect: async () => {
+    return (_jsxs(Menu, { children: [_jsx(MenuTrigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": user.name, "data-kosh-account": corner === undefined ? 'sidebar' : 'corner', className: cn('flex min-w-0 items-center gap-2 rounded-md px-1.5 py-1.5 text-sm hover:bg-muted', corner === undefined ? 'w-full' : 'rounded-full border bg-surface pe-3', collapsed && 'justify-center'), children: [_jsx(Avatar, { name: user.name, src: imageUrl('user', user.id, user.avatar) }), collapsed ? null : _jsx("span", { className: "truncate", children: user.name }), corner === undefined ? null : (_jsx(ChevronDown, { className: "size-3.5 text-muted-foreground", "aria-hidden": true }))] }) }), _jsxs(MenuContent, { align: corner === undefined ? 'start' : 'end', side: corner === undefined ? 'top' : 'bottom', className: corner === undefined ? undefined : 'max-h-[80vh] w-64 overflow-y-auto', children: [_jsxs(MenuLabel, { children: [user.name, _jsx("span", { className: "block text-xs font-normal text-muted-foreground", children: user.login })] }), registry.userPages().map((p) => (_jsx(MenuItem, { onSelect: () => void navigate({ to: '/me/$page', params: { page: p.name } }), children: t(p.label) }, p.name))), canDevelop ? (_jsx(MenuCheckboxItem, { checked: developer, onCheckedChange: (on) => setDeveloper(on === true), children: t('explain.developerMode') })) : null, corner === undefined ? null : (_jsxs(_Fragment, { children: [corner.companies.length < 2 && !user.administrator ? null : (_jsxs(_Fragment, { children: [_jsx(MenuSeparator, {}), _jsx(MenuLabel, { children: t('shell.company') }), corner.companies.length < 2
+                                        ? null
+                                        : corner.companies.map((c) => (_jsx(MenuCheckboxItem, { checked: c.id === corner.current, onCheckedChange: () => {
+                                                if (c.id !== corner.current)
+                                                    corner.onSwitch(c.id);
+                                            }, children: c.name }, c.id))), user.administrator ? (_jsxs(MenuItem, { onSelect: () => void navigate({
+                                            to: '/$app/a/$action',
+                                            params: { app: 'settings', action: 'settings.action_companies' },
+                                        }), children: [_jsx(Building2, { "aria-hidden": true }), t(corner.companies.length < 2 ? 'shell.addCompany' : 'shell.manageCompanies')] })) : null] })), _jsx(MenuSeparator, {}), _jsx(MenuLabel, { children: t('shell.language') }), LANGUAGES.map((l) => (_jsx(MenuCheckboxItem, { checked: lang === l.code, onCheckedChange: () => setLang(l.code), children: _jsx("span", { lang: l.code.replace('_', '-'), children: l.name }) }, l.code))), _jsx(MenuSeparator, {}), _jsx(MenuLabel, { children: t('shell.theme') }), ['light', 'dark', 'system'].map((choice) => (_jsx(MenuCheckboxItem, { checked: theme === choice, onCheckedChange: () => setTheme(choice), children: t(`shell.${choice}`) }, choice))), _jsx(MenuLabel, { children: t('shell.density') }), ['comfortable', 'compact'].map((choice) => (_jsx(MenuCheckboxItem, { checked: density === choice, onCheckedChange: () => setDensity(choice), children: t(`views.${choice}`) }, choice)))] })), _jsx(MenuSeparator, {}), _jsxs(MenuItem, { onSelect: async () => {
                             await api.logout();
                             queryClient.clear();
                             await dropOfflineCache(persister);
@@ -248,7 +261,7 @@ function Shell() {
             setDrawer(false);
             setPalette(true);
         }, top: _jsx(CompanyBlock, { me: user, company: current, collapsed: inDrawer ? false : collapsed, onChange: switchCompany }), bottom: _jsx(UserMenu, { user: user, collapsed: inDrawer ? false : collapsed }), onNavigate: inDrawer ? () => setDrawer(false) : undefined }));
-    return (_jsx(KoshProvider, { api: api, registry: registry, uid: user.id, companyId: current, lang: lang, tz: Intl.DateTimeFormat().resolvedOptions().timeZone, grouping: user.groupings?.[String(current)] ?? 'international', accent: user.accents?.[String(current)] ?? null, ...(realtime === undefined ? {} : { realtime }), ...(offline === undefined ? {} : { offline }), switchCompany: switchCompany, children: _jsx(ToastProvider, { children: _jsxs(DesignProvider, { children: [_jsx(OfflineAgent, { uid: user.id }), _jsxs(PaletteContext.Provider, { value: openPalette, children: [_jsx("a", { href: "#content", className: "sr-only focus:not-sr-only focus:absolute focus:start-2 focus:top-2 focus:z-50 focus:rounded focus:bg-surface focus:px-3 focus:py-2", children: t('shell.skip') }), params.app === undefined ? (_jsxs("div", { className: "flex min-h-screen flex-col", children: [_jsxs("div", { className: "flex h-14 items-center gap-2 px-4 lg:px-6", children: [userPage === undefined ? null : (_jsxs(Link, { to: "/", className: "flex items-center gap-1.5 rounded-md px-2 py-1 text-sm text-muted-foreground hover:bg-muted hover:text-foreground", children: [_jsx(House, { className: "size-4", "aria-hidden": true }), t('shell.home')] })), _jsx("span", { className: "flex-1" }), registry
+    return (_jsx(KoshProvider, { api: api, registry: registry, uid: user.id, companyId: current, lang: lang, tz: Intl.DateTimeFormat().resolvedOptions().timeZone, grouping: user.groupings?.[String(current)] ?? 'international', accent: user.accents?.[String(current)] ?? null, ...(realtime === undefined ? {} : { realtime }), ...(offline === undefined ? {} : { offline }), switchCompany: switchCompany, canDevelop: user.developer === true, children: _jsx(ToastProvider, { children: _jsxs(DesignProvider, { children: [_jsx(OfflineAgent, { uid: user.id }), _jsxs(PaletteContext.Provider, { value: openPalette, children: [_jsx("a", { href: "#content", className: "sr-only focus:not-sr-only focus:absolute focus:start-2 focus:top-2 focus:z-50 focus:rounded focus:bg-surface focus:px-3 focus:py-2", children: t('shell.skip') }), params.app === undefined ? (_jsxs("div", { className: "flex min-h-screen flex-col", children: [_jsxs("div", { className: "flex h-14 items-center gap-2 px-4 lg:px-6", children: [userPage === undefined ? null : (_jsxs(Link, { to: "/", className: "flex items-center gap-1.5 rounded-md px-2 py-1 text-sm text-muted-foreground hover:bg-muted hover:text-foreground", children: [_jsx(House, { className: "size-4", "aria-hidden": true }), t('shell.home')] })), _jsx("span", { className: "flex-1" }), registry
                                                 .headerItems()
                                                 .filter((item) => item.home)
                                                 .map(({ name, component: Item }) => (_jsx(Item, { api: api }, name))), _jsx(UserMenu, { user: user, collapsed: false, corner: {
@@ -390,7 +403,7 @@ function WindowActionPage() {
             },
         });
     };
-    return (_jsxs("section", { className: "grid gap-3", "aria-labelledby": "action-title", children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-2", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("h1", { id: "action-title", className: "text-lg font-semibold", children: action.data.label ?? served.data.view.label ?? model }), served.data.operations.create && action.data.views.includes('form') ? (_jsxs(_Fragment, { children: [_jsxs(Button, { variant: "primary", size: "sm", "data-kosh-new": true, onClick: () => open('new'), children: [_jsx(Plus, { "aria-hidden": true }), t('views.new')] }), registry.createAssists().map((Assist, i) => (_jsx(Assist
+    return (_jsxs("section", { className: "grid gap-3", "aria-labelledby": "action-title", children: [_jsxs("div", { className: "flex flex-wrap items-center justify-between gap-2", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("h1", { id: "action-title", className: "text-lg font-semibold", children: _jsx(Explain, { model: model, target: { model: true }, children: action.data.label ?? served.data.view.label ?? model }) }), served.data.operations.create && action.data.views.includes('form') ? (_jsxs(_Fragment, { children: [_jsxs(Button, { variant: "primary", size: "sm", "data-kosh-new": true, onClick: () => open('new'), children: [_jsx(Plus, { "aria-hidden": true }), t('views.new')] }), registry.createAssists().map((Assist, i) => (_jsx(Assist
                                     // biome-ignore lint/suspicious/noArrayIndexKey: registered once at start, never reordered
                                     , { api: api, model: model, onCreate: (values, proposed) => {
                                             setPrefill(actionId, { values, proposed });
@@ -489,6 +502,19 @@ function OpenRecordPage() {
         return _jsx(Alert, { children: t('app.notFound') });
     return (_jsx(Navigate, { to: "/$app/a/$action/$id", params: { app: route.app, action: route.action, id }, replace: true }));
 }
+/** A model's list where this user may open it (the explain popovers' relation links, RFC 0031 §3.1). */
+function OpenModelPage() {
+    const { api } = useServices();
+    const { t } = useTranslation();
+    const { model } = useParams({ strict: false });
+    const routes = useQuery({ queryKey: ['routes'], queryFn: () => api.routes() });
+    if (routes.isPending)
+        return _jsx(Spinner, { label: t('app.loading') });
+    const route = routes.data?.[model];
+    if (route?.app === undefined)
+        return _jsx(Alert, { children: t('app.notFound') });
+    return (_jsx(Navigate, { to: "/$app/a/$action", params: { app: route.app, action: route.action }, replace: true }));
+}
 function ActivatePage() {
     const navigate = useNavigate();
     return _jsx(Activate, { api: useServices().api, onSignedIn: () => void navigate({ to: '/' }) });
@@ -560,6 +586,11 @@ const openRoute = createRoute({
     path: '/open/$model/$id',
     component: OpenRecordPage,
 });
+const openModelRoute = createRoute({
+    getParentRoute: () => shellRoute,
+    path: '/open/$model',
+    component: OpenModelPage,
+});
 /** A personal page from the user menu (`registry.registerUserPage`), outside any app. */
 function UserPage() {
     const { page } = useParams({ strict: false });
@@ -583,6 +614,7 @@ const routeTree = rootRoute.addChildren([
     shellRoute.addChildren([
         indexRoute,
         openRoute,
+        openModelRoute,
         userPageRoute,
         appRoute,
         actionRoute,

package/dist/ui/components/AppIcon.js

@@ -3,7 +3,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * App icons by name (`app.icon` in a module manifest): the launcher's tiles and the App manager's cards. Names
  * follow Lucide; an unknown name shows a neutral grid, never a broken image.
  */
-import { BookOpen, Boxes, Briefcase, Building, Building2, CalendarDays, ChartColumn, Factory, FolderKanban, Globe, Landmark, LayoutGrid, ListChecks, LockKeyhole, Mail, MessageSquare, MessagesSquare, Package, PencilRuler, Plug, Receipt, Ruler, ScrollText, Settings, ShieldCheck, ShoppingCart, Sparkles, Store, Ticket, TrendingUp, UserPlus, Users, Wallet, Warehouse, Workflow, Wrench, } from 'lucide-react';
+import { BadgeCheck, Banknote, BookOpen, Boxes, Briefcase, Building, Building2, CalendarDays, ChartColumn, ClipboardList, Clock, Factory, FolderKanban, FolderOpen, Globe, Landmark, LayoutGrid, LifeBuoy, ListChecks, LockKeyhole, Mail, MessageSquare, MessagesSquare, Package, PencilRuler, Plug, Receipt, Ruler, ScrollText, Settings, ShieldCheck, ShoppingCart, Signature, Sparkles, Store, Ticket, TrendingUp, UserPlus, Users, Wallet, Warehouse, Workflow, Wrench, } from 'lucide-react';
 import { cn } from '../lib/cn.js';
 const ICONS = {
     settings: Settings,
@@ -50,10 +50,17 @@ const ICONS = {
     eventhub: Ticket,
     sites: Globe,
     counter: Store,
+    spend: Wallet,
+    requests: ClipboardList,
+    attendance: Clock,
+    payroll: Banknote,
+    helpdesk: LifeBuoy,
+    documents: FolderOpen,
+    sign: Signature,
+    approvals: BadgeCheck,
     event: Ticket,
     trade_finance: Landmark,
     maintenance: Wrench,
-    mrp: Factory,
     stock: Warehouse,
     recruitment: UserPlus,
     hr: Briefcase,

package/dist/ui/components/Explain.d.ts

@@ -0,0 +1,69 @@
+import type { ReactElement, ReactNode } from 'react';
+export interface ExplainedField {
+    readonly key: string;
+    readonly label: string;
+    readonly kind: string;
+    readonly help: string | null;
+    readonly target: string | null;
+    readonly inverse: string | null;
+    readonly required: boolean;
+    readonly readonly: boolean;
+    readonly stored: boolean;
+    readonly computed: boolean;
+    readonly depends: readonly string[];
+    readonly hasDefault: boolean;
+    readonly default: string | null;
+    readonly ondelete: string | null;
+    readonly translate: boolean;
+    readonly index: boolean;
+    readonly options: readonly (readonly [string, string])[] | null;
+    readonly module: string | null;
+}
+export interface Explained {
+    readonly model: string;
+    readonly label: string;
+    readonly module: string | null;
+    readonly extendedBy: readonly string[];
+    readonly fields: readonly ExplainedField[];
+    readonly transitions: readonly {
+        readonly name: string;
+        readonly field: string;
+        readonly from: readonly string[];
+        readonly to: string;
+        readonly guarded: boolean;
+        readonly message: string | null;
+        readonly requires: string | null;
+    }[];
+    readonly incoming: readonly {
+        readonly model: string;
+        readonly field: string;
+        readonly label: string;
+        readonly kind: string;
+    }[];
+}
+/** A model's explanation, fetched once per model while Developer mode is on. */
+export declare function useExplain(model: string | null | undefined): Explained | undefined;
+/** What to explain: a field, a transition (button), a domain (tile or menu), or the model itself. */
+export type ExplainTarget = {
+    readonly field: string;
+} | {
+    readonly transition: string;
+} | {
+    readonly action: string;
+    readonly domain?: unknown;
+} | {
+    readonly model: true;
+};
+/**
+ * Wraps `children` with the explain popover of `target` on `model` when Developer mode is on; renders them unchanged
+ * otherwise.
+ */
+export declare function Explain({ model, target, asChild, focusable, children, }: {
+    readonly model: string;
+    readonly target: ExplainTarget;
+    /** Attach to the child element itself (a button) instead of wrapping it in a focusable span. */
+    readonly asChild?: boolean;
+    /** Hover only, no tab stop: inside a control that is itself focusable (a clickable tile). */
+    readonly focusable?: boolean;
+    readonly children: ReactNode;
+}): ReactElement;

package/dist/ui/components/Explain.js

@@ -0,0 +1,62 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Explain popovers (RFC 0031 §3.1). With Developer mode on, a field label, a list column, a button, a stat tile or a
+ * page title opens — on hover or keyboard focus — a dark card saying what it is: the field's kind, what it points to
+ * (a link to that model's list) and back through which field, whether it is stored or computed and from what, its
+ * default and rules, the module that declared it; a button's states and guard; a model's relations in and out. The
+ * facts come from `GET /api/v1/meta/explain/:model` (developers and administrators only). Off, nothing changes.
+ */
+import { useQuery } from '@tanstack/react-query';
+import { HoverCard } from 'radix-ui';
+import { useTranslation } from 'react-i18next';
+import { useKosh } from '../context.js';
+/** A model's explanation, fetched once per model while Developer mode is on. */
+export function useExplain(model) {
+    const { api, developer } = useKosh();
+    const query = useQuery({
+        queryKey: ['kosh', 'explain', model],
+        queryFn: () => api.call('GET', `/api/v1/meta/explain/${encodeURIComponent(model ?? '')}`),
+        enabled: developer && typeof model === 'string' && model !== '',
+        staleTime: Number.POSITIVE_INFINITY,
+        retry: false,
+    });
+    return query.data;
+}
+function Row({ name, children, }) {
+    return (_jsxs("li", { className: "flex gap-2", children: [_jsx("span", { className: "shrink-0 text-neutral-400", children: name }), _jsx("span", { className: "min-w-0 break-words font-mono text-neutral-100", children: children })] }));
+}
+/** A link to a model's records, opened in a new tab (the generic list of the model). */
+function ModelLink({ model }) {
+    return (_jsx("a", { href: `/open/${encodeURIComponent(model)}`, target: "_blank", rel: "noreferrer", className: "text-sky-300 underline underline-offset-2 hover:text-sky-200", children: model }));
+}
+function Body({ model, target, }) {
+    const { t } = useTranslation();
+    const explained = useExplain(model);
+    if (explained === undefined)
+        return _jsx("p", { className: "text-neutral-400", children: t('explain.loading') });
+    const yes = t('explain.yes');
+    if ('field' in target) {
+        const f = explained.fields.find((x) => x.key === target.field);
+        if (f === undefined)
+            return _jsx("p", { className: "text-neutral-400", children: t('explain.unknown') });
+        return (_jsxs(_Fragment, { children: [f.help === null ? null : (_jsx("p", { className: "mb-2 rounded bg-sky-900/60 px-2 py-1 text-sky-100", children: f.help })), _jsxs("ul", { className: "space-y-0.5", children: [_jsx(Row, { name: t('explain.label'), children: f.label }), _jsx(Row, { name: t('explain.field'), children: f.key }), _jsx(Row, { name: t('explain.model'), children: explained.model }), _jsx(Row, { name: t('explain.type'), children: f.kind }), f.target === null ? null : (_jsxs(Row, { name: t('explain.relation'), children: [_jsx(ModelLink, { model: f.target }), f.inverse === null ? null : ` ← ${f.inverse}`] })), f.ondelete === null ? null : _jsx(Row, { name: t('explain.ondelete'), children: f.ondelete }), f.required ? _jsx(Row, { name: t('explain.required'), children: yes }) : null, f.readonly ? _jsx(Row, { name: t('explain.readonly'), children: yes }) : null, _jsx(Row, { name: t('explain.stored'), children: f.stored ? yes : t('explain.no') }), f.computed ? (_jsx(Row, { name: t('explain.computed'), children: f.depends.length === 0 ? yes : f.depends.join(', ') })) : null, f.hasDefault ? _jsx(Row, { name: t('explain.default'), children: f.default ?? '—' }) : null, f.translate ? _jsx(Row, { name: t('explain.translated'), children: yes }) : null, f.index ? _jsx(Row, { name: t('explain.indexed'), children: yes }) : null, f.options === null ? null : (_jsx(Row, { name: t('explain.selection'), children: f.options.map(([value, label]) => `[${value}] ${label}`).join(' · ') })), f.module === null ? null : _jsx(Row, { name: t('explain.module'), children: f.module })] })] }));
+    }
+    if ('transition' in target) {
+        const tr = explained.transitions.find((x) => x.name === target.transition);
+        return (_jsxs("ul", { className: "space-y-0.5", children: [_jsx(Row, { name: t('explain.button'), children: target.transition }), _jsx(Row, { name: t('explain.model'), children: explained.model }), tr === undefined ? null : (_jsxs(_Fragment, { children: [_jsxs(Row, { name: t('explain.states'), children: [`${tr.from.join(', ')} → ${tr.to}`, " (", tr.field, ")"] }), tr.guarded ? _jsx(Row, { name: t('explain.guard'), children: tr.message ?? yes }) : null, tr.requires === null ? null : _jsx(Row, { name: t('explain.requires'), children: tr.requires })] }))] }));
+    }
+    if ('action' in target)
+        return (_jsxs("ul", { className: "space-y-0.5", children: [_jsx(Row, { name: t('explain.action'), children: target.action }), _jsx(Row, { name: t('explain.model'), children: _jsx(ModelLink, { model: explained.model }) }), target.domain === undefined ? null : (_jsx(Row, { name: t('explain.domain'), children: JSON.stringify(target.domain) }))] }));
+    const outgoing = explained.fields.filter((f) => f.target !== null);
+    return (_jsxs("ul", { className: "space-y-0.5", children: [_jsx(Row, { name: t('explain.model'), children: explained.model }), explained.module === null ? null : _jsx(Row, { name: t('explain.module'), children: explained.module }), explained.extendedBy.length === 0 ? null : (_jsx(Row, { name: t('explain.extendedBy'), children: explained.extendedBy.join(', ') })), _jsx("li", { className: "pt-1 text-neutral-400", children: t('explain.out', { count: outgoing.length }) }), outgoing.map((f) => (_jsxs("li", { className: "font-mono text-neutral-100", children: [f.key, " (", f.kind, ") \u2192 ", _jsx(ModelLink, { model: f.target })] }, f.key))), _jsx("li", { className: "pt-1 text-neutral-400", children: t('explain.in', { count: explained.incoming.length }) }), explained.incoming.map((r) => (_jsxs("li", { className: "font-mono text-neutral-100", children: [_jsx(ModelLink, { model: r.model }), ".", r.field, " (", r.kind, ")"] }, `${r.model}.${r.field}`)))] }));
+}
+/**
+ * Wraps `children` with the explain popover of `target` on `model` when Developer mode is on; renders them unchanged
+ * otherwise.
+ */
+export function Explain({ model, target, asChild = false, focusable = true, children, }) {
+    const { developer } = useKosh();
+    if (!developer)
+        return _jsx(_Fragment, { children: children });
+    return (_jsxs(HoverCard.Root, { openDelay: 250, closeDelay: 150, children: [_jsx(HoverCard.Trigger, { asChild: true, children: asChild ? (children) : (_jsx("span", { tabIndex: focusable ? 0 : undefined, "data-kosh-explain": "", className: "inline-flex cursor-help items-center gap-0.5 underline decoration-dotted decoration-sky-500 underline-offset-2 outline-none focus-visible:ring-2 focus-visible:ring-sky-500", children: children })) }), _jsx(HoverCard.Portal, { children: _jsxs(HoverCard.Content, { side: "bottom", align: "start", sideOffset: 6, collisionPadding: 12, className: "z-50 max-h-[70vh] max-w-[min(32rem,calc(100vw-2rem))] overflow-auto rounded-md bg-neutral-950 p-3 text-xs leading-relaxed text-neutral-100 shadow-xl ring-1 ring-white/10", children: [_jsx(Body, { model: model, target: target }), _jsx(HoverCard.Arrow, { className: "fill-neutral-950" })] }) })] }));
+}

package/dist/ui/context.d.ts

@@ -26,13 +26,18 @@ export interface KoshContextValue {
     readonly offline?: OfflineQueue;
     /** Switches to another of the user's companies, when the shell offers it (Settings › Companies). */
     readonly switchCompany?: (company: number) => void;
+    /** Developer mode is on (RFC 0031 §3.1): fields, buttons and models explain themselves on hover. */
+    readonly developer: boolean;
+    /** The user may turn Developer mode on (administrators and developers). */
+    readonly canDevelop: boolean;
+    setDeveloper(on: boolean): void;
 }
 /** The renderer context. @throws outside {@link KoshProvider} */
 export declare function useKosh(): KoshContextValue;
 export type Density = 'comfortable' | 'compact';
 /** Applies the theme to `<html>` (the `dark` class) and follows the system when asked to. */
 declare function useTheme(): [ThemeChoice, (t: ThemeChoice) => void];
-export declare function KoshProvider({ api, registry, uid, companyId, lang, tz, grouping, accent, realtime, offline, switchCompany, children, }: {
+export declare function KoshProvider({ api, registry, uid, companyId, lang, tz, grouping, accent, realtime, offline, switchCompany, canDevelop, children, }: {
     readonly api: KoshApi;
     readonly registry: Registry;
     readonly uid: number;
@@ -46,6 +51,8 @@ export declare function KoshProvider({ api, registry, uid, companyId, lang, tz,
     readonly realtime?: RealtimeClient;
     readonly offline?: OfflineQueue;
     readonly switchCompany?: (company: number) => void;
+    /** The user may turn Developer mode on (`me.developer`). */
+    readonly canDevelop?: boolean;
     readonly children: ReactNode;
 }): ReactElement;
 /** Theme switching without a signed-in user (the sign-in page). */

package/dist/ui/context.js

@@ -16,6 +16,31 @@ export function useKosh() {
 }
 const THEME_KEY = 'kosh.theme';
 const DENSITY_KEY = 'kosh.density';
+const DEVELOPER_KEY = 'kosh.developer';
+function readDeveloper() {
+    try {
+        return localStorage.getItem(DEVELOPER_KEY) === 'on';
+    }
+    catch {
+        return false;
+    }
+}
+/** Developer mode, remembered per browser. */
+function useDeveloper() {
+    const [on, setOn] = useState(readDeveloper);
+    useEffect(() => {
+        try {
+            if (on)
+                localStorage.setItem(DEVELOPER_KEY, 'on');
+            else
+                localStorage.removeItem(DEVELOPER_KEY);
+        }
+        catch {
+            // storage unavailable: the choice lasts for this page only
+        }
+    }, [on]);
+    return [on, setOn];
+}
 function readDensity() {
     try {
         return JSON.parse(localStorage.getItem(DENSITY_KEY) ?? 'null') === 'compact'
@@ -87,9 +112,11 @@ function useTheme() {
     }, [theme]);
     return [theme, setTheme];
 }
-export function KoshProvider({ api, registry, uid, companyId, lang, tz, grouping, accent, realtime, offline, switchCompany, children, }) {
+export function KoshProvider({ api, registry, uid, companyId, lang, tz, grouping, accent, realtime, offline, switchCompany, canDevelop = false, children, }) {
     const [theme, setTheme] = useTheme();
     const [density, setDensity] = useDensity();
+    const [developerOn, setDeveloper] = useDeveloper();
+    const developer = canDevelop && developerOn;
     useAccent(accent);
     const format = useMemo(() => createFormatter(lang, tz, grouping === undefined ? {} : { grouping }), [lang, tz, grouping]);
     const value = useMemo(() => ({
@@ -102,6 +129,9 @@ export function KoshProvider({ api, registry, uid, companyId, lang, tz, grouping
         setTheme,
         density,
         setDensity,
+        developer,
+        canDevelop,
+        setDeveloper,
         ...(realtime === undefined ? {} : { realtime }),
         ...(offline === undefined ? {} : { offline }),
         ...(switchCompany === undefined ? {} : { switchCompany }),
@@ -115,6 +145,9 @@ export function KoshProvider({ api, registry, uid, companyId, lang, tz, grouping
         setTheme,
         density,
         setDensity,
+        developer,
+        canDevelop,
+        setDeveloper,
         realtime,
         offline,
         switchCompany,

package/dist/ui/i18n/messages.d.ts

@@ -3,6 +3,39 @@
  * Modules ship their own namespaces; labels from model metadata come translated by the server (`Accept-Language`).
  */
 export declare const en: {
+    explain: {
+        developerMode: string;
+        loading: string;
+        unknown: string;
+        yes: string;
+        no: string;
+        label: string;
+        field: string;
+        model: string;
+        type: string;
+        relation: string;
+        ondelete: string;
+        required: string;
+        readonly: string;
+        stored: string;
+        computed: string;
+        default: string;
+        translated: string;
+        indexed: string;
+        selection: string;
+        module: string;
+        button: string;
+        states: string;
+        guard: string;
+        requires: string;
+        action: string;
+        domain: string;
+        extendedBy: string;
+        out_one: string;
+        out_other: string;
+        in_one: string;
+        in_other: string;
+    };
     app: {
         name: string;
         loading: string;
@@ -48,6 +81,9 @@ export declare const en: {
         home: string;
         appNamed: string;
         switchCompany: string;
+        companyMenu: string;
+        manageCompanies: string;
+        addCompany: string;
         sidebar: string;
         collapseSidebar: string;
         expandSidebar: string;
@@ -92,6 +128,7 @@ export declare const en: {
         exportFailed: string;
         columns: string;
         pinned: string;
+        pinColumn: string;
         resetWidths: string;
         resize: string;
         density: string;
@@ -126,6 +163,7 @@ export declare const en: {
         leaveConfirm: string;
         transitionDone: string;
         deleted: string;
+        duplicated: string;
         breadcrumbs: string;
         saving: string;
         unsaved: string;
@@ -150,6 +188,8 @@ export declare const en: {
         discard: string;
         edit: string;
         delete: string;
+        duplicate: string;
+        actions: string;
         confirmDelete: string;
         saved: string;
         total: string;