shutro-erp 0.3.6 → 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

@@ -18,6 +18,7 @@ import { createContext, useCallback, useContext, useEffect, useMemo, useState, }
 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';
@@ -167,10 +168,10 @@ function CompanyBlock({ me, company, collapsed, onChange, }) {
 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 && !user.administrator ? null : (_jsxs(_Fragment, { children: [_jsx(MenuSeparator, {}), _jsx(MenuLabel, { children: t('shell.company') }), corner.companies.length < 2
+    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)
@@ -260,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: {
@@ -402,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 });
@@ -501,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: '/' }) });
@@ -572,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 });
@@ -595,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 { BadgeCheck, Banknote, BookOpen, Boxes, Briefcase, Building, Building2, CalendarDays, ChartColumn, 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 { 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,
@@ -51,6 +51,7 @@ const ICONS = {
     sites: Globe,
     counter: Store,
     spend: Wallet,
+    requests: ClipboardList,
     attendance: Clock,
     payroll: Banknote,
     helpdesk: LifeBuoy,
@@ -60,7 +61,6 @@ const ICONS = {
     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;
@@ -130,6 +163,7 @@ export declare const en: {
         leaveConfirm: string;
         transitionDone: string;
         deleted: string;
+        duplicated: string;
         breadcrumbs: string;
         saving: string;
         unsaved: string;
@@ -154,6 +188,8 @@ export declare const en: {
         discard: string;
         edit: string;
         delete: string;
+        duplicate: string;
+        actions: string;
         confirmDelete: string;
         saved: string;
         total: string;

package/dist/ui/i18n/messages.js

@@ -3,6 +3,39 @@
  * Modules ship their own namespaces; labels from model metadata come translated by the server (`Accept-Language`).
  */
 export const en = {
+    explain: {
+        developerMode: 'Developer mode',
+        loading: 'Loading…',
+        unknown: 'Not a field of this model.',
+        yes: 'yes',
+        no: 'no',
+        label: 'Label',
+        field: 'Field',
+        model: 'Model',
+        type: 'Type',
+        relation: 'Relation',
+        ondelete: 'On delete',
+        required: 'Required',
+        readonly: 'Read-only',
+        stored: 'Stored',
+        computed: 'Computed from',
+        default: 'Default',
+        translated: 'Translated',
+        indexed: 'Indexed',
+        selection: 'Values',
+        module: 'Module',
+        button: 'Button',
+        states: 'States',
+        guard: 'Guard',
+        requires: 'Requires',
+        action: 'Action',
+        domain: 'Domain',
+        extendedBy: 'Extended by',
+        out_one: '{{count}} relation out',
+        out_other: '{{count}} relations out',
+        in_one: '{{count}} relation in',
+        in_other: '{{count}} relations in',
+    },
     app: {
         name: 'Shutro ERP',
         loading: 'Loading…',
@@ -127,6 +160,7 @@ export const en = {
         leaveConfirm: 'You have unsaved changes. Leave without saving?',
         transitionDone: '{{action}}: done',
         deleted: 'Deleted',
+        duplicated: 'Duplicated: this is the copy',
         breadcrumbs: 'Breadcrumbs',
         saving: 'Saving…',
         unsaved: 'Unsaved changes',
@@ -151,6 +185,8 @@ export const en = {
         discard: 'Discard',
         edit: 'Edit',
         delete: 'Delete',
+        duplicate: 'Duplicate',
+        actions: 'Actions',
         confirmDelete: 'Delete this record?',
         saved: 'Saved',
         total: 'Total',
@@ -337,6 +373,39 @@ export const en = {
     },
 };
 export const bn = {
+    explain: {
+        developerMode: 'ডেভেলপার মোড',
+        loading: 'লোড হচ্ছে…',
+        unknown: 'এই মডেলের ফিল্ড নয়।',
+        yes: 'হ্যাঁ',
+        no: 'না',
+        label: 'লেবেল',
+        field: 'ফিল্ড',
+        model: 'মডেল',
+        type: 'ধরন',
+        relation: 'সম্পর্ক',
+        ondelete: 'মুছলে',
+        required: 'আবশ্যক',
+        readonly: 'শুধু পড়া যায়',
+        stored: 'সংরক্ষিত',
+        computed: 'যা থেকে হিসাব হয়',
+        default: 'ডিফল্ট',
+        translated: 'অনূদিত',
+        indexed: 'ইনডেক্সড',
+        selection: 'মান',
+        module: 'মডিউল',
+        button: 'বাটন',
+        states: 'অবস্থা',
+        guard: 'শর্ত',
+        requires: 'প্রয়োজন',
+        action: 'অ্যাকশন',
+        domain: 'ডোমেইন',
+        extendedBy: 'যা বাড়িয়েছে',
+        out_one: '{{count}}টি বাইরের সম্পর্ক',
+        out_other: '{{count}}টি বাইরের সম্পর্ক',
+        in_one: '{{count}}টি ভেতরের সম্পর্ক',
+        in_other: '{{count}}টি ভেতরের সম্পর্ক',
+    },
     app: {
         name: 'কোষ',
         loading: 'লোড হচ্ছে…',
@@ -461,6 +530,7 @@ export const bn = {
         leaveConfirm: 'পরিবর্তন সংরক্ষণ করা হয়নি। সংরক্ষণ না করেই চলে যাবেন?',
         transitionDone: '{{action}}: সম্পন্ন',
         deleted: 'মুছে ফেলা হয়েছে',
+        duplicated: 'অনুলিপি হয়েছে: এটি অনুলিপি',
         breadcrumbs: 'অবস্থান',
         saving: 'সংরক্ষণ হচ্ছে…',
         unsaved: 'অসংরক্ষিত পরিবর্তন',
@@ -485,6 +555,8 @@ export const bn = {
         discard: 'বাতিল',
         edit: 'সম্পাদনা',
         delete: 'মুছুন',
+        duplicate: 'অনুলিপি করুন',
+        actions: 'কাজ',
         confirmDelete: 'এই রেকর্ডটি মুছবেন?',
         saved: 'সংরক্ষিত',
         total: 'মোট',

package/dist/ui/index.d.ts

@@ -11,6 +11,7 @@ export { ApiError, type ApiOptions, type AppEntry, type CurrentUser, createKoshA
 export { KoshApp, type KoshAppProps, useLanguage } from './app.js';
 export { AppIcon } from './components/AppIcon.js';
 export * from './components/Avatar.js';
+export { Explain, type Explained, type ExplainedField, type ExplainTarget, useExplain, } from './components/Explain.js';
 export * from './components/primitives.js';
 export { type KoshContextValue, KoshProvider, type ThemeChoice, useKosh, useTheme, } from './context.js';
 export { type DesignContextValue, DesignProvider, type DesignSpot, useDesign, } from './design.js';
@@ -26,7 +27,7 @@ export { type Prefill, setPrefill, takePrefill } from './prefill.js';
 export { registerServiceWorker } from './pwa/register.js';
 export { serviceWorkerSource, type WorkerConfig } from './pwa/worker.js';
 export { type ChangeEvent, createRealtimeClient, type PresenceUser, type RealtimeClient, type RealtimeOptions, } from './realtime.js';
-export { type ChatterAssistProps, type CreateAssistProps, type FormProps, type HeaderItemProps, type NodeComponentProps, type PageProps, Registry, RegistryError, type SearchAssistProps, type ViewProps, type WidgetProps, } from './registry.js';
+export { type ChatterAssistProps, type CreateAssistProps, type FormProps, type HeaderItemProps, type NodeComponentProps, type PageProps, Registry, RegistryError, type SearchAssistProps, type SelectionActionProps, type ViewProps, type WidgetProps, } from './registry.js';
 export { SearchBar, type SearchBarProps } from './search/SearchBar.js';
 export { Login } from './shell/Login.js';
 export { FormView } from './views/FormView.js';

package/dist/ui/index.js

@@ -15,6 +15,7 @@ export { ApiError, createKoshApi, NetworkError, } from './api.js';
 export { KoshApp, useLanguage } from './app.js';
 export { AppIcon } from './components/AppIcon.js';
 export * from './components/Avatar.js';
+export { Explain, useExplain, } from './components/Explain.js';
 export * from './components/primitives.js';
 export { KoshProvider, useKosh, useTheme, } from './context.js';
 export { DesignProvider, useDesign, } from './design.js';

package/dist/ui/registry.d.ts

@@ -93,6 +93,14 @@ export interface CreateAssistProps {
     /** Opens a new record with these values, `proposed` marked as proposals. */
     readonly onCreate: (values: Readonly<Record<string, unknown>>, proposed: readonly string[]) => void;
 }
+/** Props of a selection action: a control in a list's bar of selected rows (Send by email). */
+export interface SelectionActionProps {
+    readonly api: KoshApi;
+    readonly model: string;
+    readonly ids: readonly number[];
+    /** Clears the selection, refreshes the list and says `message`. */
+    readonly done: (message: string, tone?: 'info' | 'danger') => void;
+}
 /** Props of a page: what a client action opens (`{ type: 'client', page: 'settings.Apps' }`). */
 export interface PageProps {
     readonly api: KoshApi;
@@ -177,6 +185,12 @@ export declare class Registry {
     }): this;
     /** The create assistants, in registration order. */
     createAssists(): readonly ComponentType<CreateAssistProps>[];
+    /** Controls in every list's bar of selected rows; each decides whether it applies to the model. */
+    registerSelectionAction(name: string, component: ComponentType<SelectionActionProps>, options?: {
+        readonly replace?: boolean;
+    }): this;
+    /** The selection actions, in registration order. */
+    selectionActions(): readonly ComponentType<SelectionActionProps>[];
     page(name: string): ComponentType<PageProps> | undefined;
     /** A copy, for an app that changes entries without touching the defaults. */
     clone(): Registry;

package/dist/ui/registry.js

@@ -16,6 +16,7 @@ export class Registry {
         searchAssist: new Map(),
         chatterAssist: new Map(),
         createAssist: new Map(),
+        selectionAction: new Map(),
     };
     #add(kind, name, component, replace) {
         if (this.#entries[kind].has(name) && !replace)
@@ -118,6 +119,14 @@ export class Registry {
     createAssists() {
         return [...this.#entries.createAssist.values()];
     }
+    /** Controls in every list's bar of selected rows; each decides whether it applies to the model. */
+    registerSelectionAction(name, component, options = {}) {
+        return this.#add('selectionAction', name, component, options.replace === true);
+    }
+    /** The selection actions, in registration order. */
+    selectionActions() {
+        return [...this.#entries.selectionAction.values()];
+    }
     page(name) {
         return this.#entries.page.get(name);
     }
@@ -133,6 +142,7 @@ export class Registry {
             'searchAssist',
             'chatterAssist',
             'createAssist',
+            'selectionAction',
         ])
             for (const [name, c] of this.#entries[kind])
                 copy.#entries[kind].set(name, c);

package/dist/ui/views/FormView.d.ts

@@ -1,3 +1,9 @@
+/**
+ * The form renderer (RFC 0007 §5): statusbar and transition buttons from the served view (only what the user may
+ * run, from the current state), groups, notebooks, editable lines, registered components (escape hatches), onchange
+ * assistance, and saves with compare-and-set (a record changed by someone else since it was opened is not
+ * overwritten: the user reloads). Conditions only decide display; the server re-checks every write.
+ */
 import { type ReactElement } from 'react';
 import type { FormProps } from '../registry.js';
 /** The default form renderer. */