@orthacms/bootstrap-admin 0.0.0-reserve.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ortha CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @orthacms/bootstrap-admin
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/bootstrap-admin
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createAdmin } from './lib/createAdmin';
+export type { AdminPlugin, RouteItem, CreateAdminOptions } from './lib/types/adminPlugin';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACR,WAAW,EACX,SAAS,EACT,kBAAkB,EACrB,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { createAdmin } from './lib/createAdmin';

package/dist/lib/AppErrorBoundary/index.d.ts

@@ -0,0 +1,40 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+/** Props for {@link AppErrorBoundary}. */
+type AppErrorBoundaryProps = {
+    /** The routed application tree being isolated. */
+    children: ReactNode;
+};
+type AppErrorBoundaryState = {
+    failed: boolean;
+};
+/**
+ * The host's last line of defence: catches a render-phase throw from anywhere
+ * in the routed tree.
+ *
+ * Without it a single misbehaving plugin takes the whole product with it. React
+ * unmounts the entire tree when a throw reaches the root, so `#root` is left
+ * with **zero children** — no sidebar to navigate away with, no message, nothing
+ * to focus, and no hint that reloading is the fix. The two realistic causes are
+ * a **lazy chunk that never arrives** (a deploy while the tab was open leaves
+ * the browser asking for content-hashed files that no longer exist; `Suspense`
+ * handles waiting, not failing, so it re-throws) and a page that reads an
+ * unexpected shape out of an API response.
+ *
+ * Deliberately mounted **outside** `BrowserRouter` so a throw from the router
+ * itself is caught too, and outside the `Toaster` so notifications survive the
+ * failure. It is not a substitute for a narrower boundary: a plugin that can
+ * usefully degrade one region should catch there (as `insights-admin` does
+ * per-widget, and `identity-admin` does around the auth screens), because a
+ * boundary this high can only offer a reload.
+ *
+ * A class component because React still offers no hook equivalent of
+ * `componentDidCatch`, and a render-phase throw is exactly what needs catching.
+ */
+export declare class AppErrorBoundary extends Component<AppErrorBoundaryProps, AppErrorBoundaryState> {
+    state: AppErrorBoundaryState;
+    static getDerivedStateFromError(): AppErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/AppErrorBoundary/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/AppErrorBoundary/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EACH,SAAS,EAGT,KAAK,SAAS,EACd,KAAK,SAAS,EACjB,MAAM,OAAO,CAAC;AA8Ff,0CAA0C;AAC1C,KAAK,qBAAqB,GAAG;IACzB,kDAAkD;IAClD,QAAQ,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF,KAAK,qBAAqB,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAiB,SAAQ,SAAS,CAC3C,qBAAqB,EACrB,qBAAqB,CACxB;IACY,KAAK,EAAE,qBAAqB,CAAqB;IAE1D,MAAM,CAAC,wBAAwB,IAAI,qBAAqB;IAI/C,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAQtD,MAAM,IAAI,SAAS;CAK/B"}

package/dist/lib/AppErrorBoundary/index.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component, useEffect, useRef } from 'react';
+import { defineMessages, useIntl } from 'react-intl';
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Logo } from '@orthacms/design-system';
+/** Intl descriptors for the fallback, co-located with it. */
+const messages = defineMessages({
+    title: {
+        id: 'app.errorBoundary.title',
+        defaultMessage: 'Something went wrong'
+    },
+    description: {
+        id: 'app.errorBoundary.description',
+        defaultMessage: 'This page stopped working. Reloading usually fixes it — if it keeps happening, the last thing you did is worth reporting.'
+    },
+    reload: {
+        id: 'app.errorBoundary.reload',
+        defaultMessage: 'Reload the page'
+    }
+});
+/**
+ * The card shown when the routed tree throws.
+ *
+ * A function component because the boundary itself must be a class, and because
+ * the copy has to go through the host's single `IntlProvider` like every other
+ * string in the admin.
+ *
+ * It takes focus on mount. The failure replaces whatever the user was reading
+ * with no navigation the browser would report, so without this focus stays on a
+ * control that no longer exists and the browser resets it to `<body>`: a
+ * keyboard user tabs from the top of a page nobody told them they had reached,
+ * and a screen reader keeps reading a buffer of content that has been unmounted.
+ * The heading carries `tabIndex={-1}` so it can receive focus without joining
+ * the tab order.
+ */
+function AppCrashed() {
+    const intl = useIntl();
+    const headingRef = useRef(null);
+    useEffect(() => {
+        headingRef.current?.focus();
+    }, []);
+    return (_jsxs("div", { className: "flex min-h-svh flex-col items-center justify-center gap-6 bg-muted p-6", children: [_jsx(Logo, {}), _jsxs(Card, { className: "w-full max-w-md", children: [_jsxs(CardHeader, { className: "text-center", children: [_jsx(CardTitle, { asChild: true, children: _jsx("h1", { ref: headingRef, tabIndex: -1, 
+                                    // Programmatic focus on a heading is `:focus-visible`
+                                    // in Chrome, which draws a box around the page title
+                                    // as if it were something to interact with. Safe to
+                                    // suppress only because `tabIndex={-1}` keeps it out
+                                    // of the tab order, so nobody can navigate onto it
+                                    // and need the indicator.
+                                    className: "text-xl font-semibold outline-none", children: intl.formatMessage(messages.title) }) }), _jsx(CardDescription, { children: intl.formatMessage(messages.description) })] }), _jsx(CardContent, { children: _jsx(Button, { type: "button", className: "w-full", 
+                            // A failed lazy chunk is cached as failed by the module
+                            // registry, and a render that threw on bad state will
+                            // throw again — re-rendering cannot recover either, so
+                            // only a fresh document request is offered.
+                            onClick: () => window.location.reload(), children: intl.formatMessage(messages.reload) }) })] })] }));
+}
+/**
+ * The host's last line of defence: catches a render-phase throw from anywhere
+ * in the routed tree.
+ *
+ * Without it a single misbehaving plugin takes the whole product with it. React
+ * unmounts the entire tree when a throw reaches the root, so `#root` is left
+ * with **zero children** — no sidebar to navigate away with, no message, nothing
+ * to focus, and no hint that reloading is the fix. The two realistic causes are
+ * a **lazy chunk that never arrives** (a deploy while the tab was open leaves
+ * the browser asking for content-hashed files that no longer exist; `Suspense`
+ * handles waiting, not failing, so it re-throws) and a page that reads an
+ * unexpected shape out of an API response.
+ *
+ * Deliberately mounted **outside** `BrowserRouter` so a throw from the router
+ * itself is caught too, and outside the `Toaster` so notifications survive the
+ * failure. It is not a substitute for a narrower boundary: a plugin that can
+ * usefully degrade one region should catch there (as `insights-admin` does
+ * per-widget, and `identity-admin` does around the auth screens), because a
+ * boundary this high can only offer a reload.
+ *
+ * A class component because React still offers no hook equivalent of
+ * `componentDidCatch`, and a render-phase throw is exactly what needs catching.
+ */
+export class AppErrorBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error, info) {
+        console.error('[bootstrap-admin] the application tree failed to render', error, info.componentStack);
+    }
+    render() {
+        if (!this.state.failed)
+            return this.props.children;
+        return _jsx(AppCrashed, {});
+    }
+}

package/dist/lib/DesignSystemLabels/index.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+/**
+ * Translates the design system's built-in chrome strings and hands them down
+ * through its labels context.
+ *
+ * The library ships English defaults and no i18n runtime — deliberately, it is
+ * consumed outside this app too. That left every dialog's and sheet's close
+ * button announcing "Close" in a German session, because localizing it meant
+ * passing `closeLabel` at each of twenty-odd call sites and no consumer did
+ * (`ORT-159`). Doing it once here means a new dialog is localized by existing,
+ * rather than by remembering.
+ *
+ * A call site that passes its own `closeLabel` still wins — this is the default
+ * underneath, not a ceiling.
+ */
+export declare function DesignSystemLabels({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/DesignSystemLabels/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/DesignSystemLabels/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAYhD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAevE"}

package/dist/lib/DesignSystemLabels/index.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { defineMessages, useIntl } from 'react-intl';
+import { DesignSystemLabelsProvider } from '@orthacms/design-system';
+/** Intl descriptors for the design system's own chrome, co-located here. */
+const messages = defineMessages({
+    close: {
+        id: 'designSystem.close',
+        defaultMessage: 'Close'
+    }
+});
+/**
+ * Translates the design system's built-in chrome strings and hands them down
+ * through its labels context.
+ *
+ * The library ships English defaults and no i18n runtime — deliberately, it is
+ * consumed outside this app too. That left every dialog's and sheet's close
+ * button announcing "Close" in a German session, because localizing it meant
+ * passing `closeLabel` at each of twenty-odd call sites and no consumer did
+ * (`ORT-159`). Doing it once here means a new dialog is localized by existing,
+ * rather than by remembering.
+ *
+ * A call site that passes its own `closeLabel` still wins — this is the default
+ * underneath, not a ceiling.
+ */
+export function DesignSystemLabels({ children }) {
+    const intl = useIntl();
+    // Memoized because the context value is an object: a fresh one per render
+    // would re-render every dialog and sheet in the tree for nothing.
+    const labels = useMemo(() => ({ close: intl.formatMessage(messages.close) }), [intl]);
+    return (_jsx(DesignSystemLabelsProvider, { labels: labels, children: children }));
+}

package/dist/lib/RouteAnnouncer/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Speaks the name of each new view after a client-side navigation.
+ *
+ * A single-page app changes the whole view without the browser navigating, and a
+ * screen reader is given nothing to report: `<Routes>` swaps the matched
+ * element, focus stays on the link that was activated, and the tab title is
+ * unchanged. The result is that no page change in the admin is announced at all
+ * — the archetypal SPA failure of WCAG `4.1.3 Status Messages`.
+ *
+ * This mounts one visually-hidden polite live region for the life of the app —
+ * present before any message exists, which is the precondition for a live region
+ * to be announced at all — and writes the new view's name into it on every
+ * pathname change after the first. The first is skipped deliberately: a fresh
+ * page load is a real navigation the browser already reports, and announcing it
+ * again would double up.
+ *
+ * **It waits for the heading to actually change.** Naively reading the `<h1>` a
+ * moment after the location changes announces the page the user just *left*: the
+ * incoming route is a lazy chunk behind a `Suspense` skeleton, so for the first
+ * frames of a cold navigation the only heading in the DOM is the outgoing one.
+ * Measured on a live stack before this guard existed — `/workspaces` →
+ * `/activity` announced "Workspaces" — which is worse than silence, because it
+ * tells a screen-reader user they are somewhere they have just left. So the
+ * announcer remembers the heading it last saw and polls until it finds a
+ * *different* one (a different element, or the same element with different text,
+ * which is how a page that fills its own title in asynchronously looks). If the
+ * heading never changes within {@link POLL_TIMEOUT_MS} it stays quiet rather
+ * than guess — the cost is that two routes sharing one heading text are not
+ * announced, which is the right way round.
+ *
+ * It does **not** move focus. Where focus belongs is a decision only the
+ * arriving page can make (identity's auth screens focus their own heading; a
+ * page opening an editor may want the first field), and taking it at the host
+ * would fight them. The keyboard route past the sidebar is the shell's "Skip to
+ * main content" link.
+ */
+export declare function RouteAnnouncer(): import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/RouteAnnouncer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/RouteAnnouncer/index.tsx"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,cAAc,gCAiE7B"}

package/dist/lib/RouteAnnouncer/index.js

@@ -0,0 +1,125 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { useLocation } from 'react-router-dom';
+/**
+ * How long to keep looking for the new route's heading, and how often. A
+ * private route is a lazy chunk behind a `Suspense` skeleton, so the heading
+ * that names it does not exist at the moment the location changes — and for the
+ * first ~100ms of a cold navigation the heading still in the DOM is the one
+ * belonging to the page being *left*.
+ */
+const POLL_INTERVAL_MS = 100;
+const POLL_TIMEOUT_MS = 5_000;
+/**
+ * What the announcer last saw, so it can tell "the new route has rendered" from
+ * "the old route is still on screen".
+ *
+ * Module state rather than a `useRef` on purpose: React 19's `StrictMode` mounts
+ * every effect twice in development, and a ref is re-created by that remount —
+ * so the deliberately silent first render would announce the landing page on the
+ * second pass. One host runs per document, so a module-level value has the same
+ * lifetime as the app.
+ */
+let lastPath = null;
+let lastHeading = null;
+let lastHeadingText = null;
+/**
+ * The element that names the view currently rendered, and its text.
+ *
+ * The `<h1>` is the one label every page in the admin already has and keeps
+ * accurate — unlike the document title, which most routes never set (they
+ * inherit the host HTML's "Admin"). Scoped to the `<main>` landmark when the
+ * layout provides one, so the shell's own chrome cannot be mistaken for the
+ * page.
+ */
+function readHeading() {
+    const scope = document.querySelector('main') ?? document;
+    const element = scope.querySelector('h1');
+    const text = element?.textContent?.trim();
+    return element && text ? { element, text } : null;
+}
+/**
+ * Speaks the name of each new view after a client-side navigation.
+ *
+ * A single-page app changes the whole view without the browser navigating, and a
+ * screen reader is given nothing to report: `<Routes>` swaps the matched
+ * element, focus stays on the link that was activated, and the tab title is
+ * unchanged. The result is that no page change in the admin is announced at all
+ * — the archetypal SPA failure of WCAG `4.1.3 Status Messages`.
+ *
+ * This mounts one visually-hidden polite live region for the life of the app —
+ * present before any message exists, which is the precondition for a live region
+ * to be announced at all — and writes the new view's name into it on every
+ * pathname change after the first. The first is skipped deliberately: a fresh
+ * page load is a real navigation the browser already reports, and announcing it
+ * again would double up.
+ *
+ * **It waits for the heading to actually change.** Naively reading the `<h1>` a
+ * moment after the location changes announces the page the user just *left*: the
+ * incoming route is a lazy chunk behind a `Suspense` skeleton, so for the first
+ * frames of a cold navigation the only heading in the DOM is the outgoing one.
+ * Measured on a live stack before this guard existed — `/workspaces` →
+ * `/activity` announced "Workspaces" — which is worse than silence, because it
+ * tells a screen-reader user they are somewhere they have just left. So the
+ * announcer remembers the heading it last saw and polls until it finds a
+ * *different* one (a different element, or the same element with different text,
+ * which is how a page that fills its own title in asynchronously looks). If the
+ * heading never changes within {@link POLL_TIMEOUT_MS} it stays quiet rather
+ * than guess — the cost is that two routes sharing one heading text are not
+ * announced, which is the right way round.
+ *
+ * It does **not** move focus. Where focus belongs is a decision only the
+ * arriving page can make (identity's auth screens focus their own heading; a
+ * page opening an editor may want the first field), and taking it at the host
+ * would fight them. The keyboard route past the sidebar is the shell's "Skip to
+ * main content" link.
+ */
+export function RouteAnnouncer() {
+    const { pathname } = useLocation();
+    const [announcement, setAnnouncement] = useState('');
+    useEffect(() => {
+        const initial = lastPath === null;
+        // The landing page, or a re-render on the same path: nothing changed
+        // that the user was not already told about. The landing page's heading
+        // is still recorded, so it becomes the baseline the first real
+        // navigation has to differ from.
+        const samePath = lastPath === pathname;
+        lastPath = pathname;
+        let cancelled = false;
+        let timer = 0;
+        const startedAt = Date.now();
+        // Cleared first so that going A → B → A announces "A" again: an
+        // unchanged live region is never re-read.
+        if (!initial && !samePath)
+            setAnnouncement('');
+        const tick = () => {
+            if (cancelled)
+                return;
+            const heading = readHeading();
+            const changed = heading &&
+                (heading.element !== lastHeading ||
+                    heading.text !== lastHeadingText);
+            if (heading && (initial || samePath)) {
+                // Baseline only: remember what is on screen, say nothing.
+                lastHeading = heading.element;
+                lastHeadingText = heading.text;
+                return;
+            }
+            if (changed) {
+                lastHeading = heading.element;
+                lastHeadingText = heading.text;
+                setAnnouncement(heading.text);
+                return;
+            }
+            if (Date.now() - startedAt >= POLL_TIMEOUT_MS)
+                return;
+            timer = window.setTimeout(tick, POLL_INTERVAL_MS);
+        };
+        timer = window.setTimeout(tick, POLL_INTERVAL_MS);
+        return () => {
+            cancelled = true;
+            window.clearTimeout(timer);
+        };
+    }, [pathname]);
+    return (_jsx("p", { "data-testid": "route-announcer", "aria-live": "polite", "aria-atomic": "true", className: "sr-only", children: announcement }));
+}

package/dist/lib/UnsavedChangesGuard/index.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+/**
+ * Mounts the app-wide unsaved-changes guard and supplies its confirm dialog.
+ *
+ * The guard itself is copy-free (it lives in `utils-admin`, which owns no
+ * strings); this host binds it to the design-system dialog and the app's single
+ * `IntlProvider`, so every form in every plugin gets the same prompt without
+ * each one re-implementing it.
+ */
+export declare function UnsavedChangesGuard({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/UnsavedChangesGuard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/UnsavedChangesGuard/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAyBvC;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAoBxE"}

package/dist/lib/UnsavedChangesGuard/index.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { defineMessages, useIntl } from 'react-intl';
+import { ConfirmDialog } from '@orthacms/design-system';
+import { UnsavedChangesProvider } from '@orthacms/utils-admin';
+const messages = defineMessages({
+    title: {
+        id: 'app.unsaved.title',
+        defaultMessage: 'Discard your unsaved changes?'
+    },
+    body: {
+        id: 'app.unsaved.body',
+        defaultMessage: 'You have edits on this page that haven’t been saved. Leaving now loses them.'
+    },
+    confirm: {
+        id: 'app.unsaved.confirm',
+        defaultMessage: 'Leave and discard'
+    },
+    cancel: {
+        id: 'app.unsaved.cancel',
+        defaultMessage: 'Keep editing'
+    }
+});
+/**
+ * Mounts the app-wide unsaved-changes guard and supplies its confirm dialog.
+ *
+ * The guard itself is copy-free (it lives in `utils-admin`, which owns no
+ * strings); this host binds it to the design-system dialog and the app's single
+ * `IntlProvider`, so every form in every plugin gets the same prompt without
+ * each one re-implementing it.
+ */
+export function UnsavedChangesGuard({ children }) {
+    const intl = useIntl();
+    return (_jsx(UnsavedChangesProvider, { dialog: ({ open, onOpenChange, onConfirm }) => (_jsx(ConfirmDialog, { open: open, onOpenChange: onOpenChange, title: intl.formatMessage(messages.title), description: intl.formatMessage(messages.body), confirmLabel: intl.formatMessage(messages.confirm), cancelLabel: intl.formatMessage(messages.cancel), confirmVariant: "destructive", onConfirm: onConfirm })), children: children }));
+}

package/dist/lib/createAdmin/index.d.ts

@@ -0,0 +1,24 @@
+import type { CreateAdminOptions } from '../types/adminPlugin';
+/**
+ * Bootstraps the Ortha CMS admin app: mounts the React root, wraps it in
+ * the data, i18n, and router providers, and renders the routes contributed by
+ * every plugin.
+ *
+ * Plugins author user-facing strings with `react-intl` (`defineMessages` +
+ * `useIntl`), so the host provides a single `IntlProvider`. Messages are
+ * resolved from each descriptor's `defaultMessage`; a translation catalogue
+ * can be wired in here later without touching plugins.
+ *
+ * Server state is fetched with TanStack Query, so the host also provides one
+ * `QueryClient`. Plugins call `useQuery`/`useMutation` (e.g. identity's
+ * `useLoginMutation`) without owning a client of their own.
+ *
+ * Routes split by `public`: public routes mount as top-level siblings, while
+ * every other route mounts under a single pathless parent that renders the
+ * `layout` a plugin contributed (or a bare `<Outlet/>`). The host is
+ * auth-agnostic — it does not know that `layout` may wrap its children in a
+ * gate; the contributing plugin (the shell) owns that. A `public:false` route
+ * with no gating `layout` therefore renders ungated.
+ */
+export declare function createAdmin(options: CreateAdminOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/createAdmin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/createAdmin/index.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA8J5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CA6G7D"}

package/dist/lib/createAdmin/index.js

@@ -0,0 +1,209 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { StrictMode } from 'react';
+import * as ReactDOM from 'react-dom/client';
+import { BrowserRouter, Navigate, Outlet, Route, Routes } from 'react-router-dom';
+import { IntlProvider } from 'react-intl';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { queryClient } from '@orthacms/utils-admin';
+import { AppearanceProvider, TooltipProvider, Toaster } from '@orthacms/design-system';
+import { UnsavedChangesGuard } from '../UnsavedChangesGuard';
+import { AppErrorBoundary } from '../AppErrorBoundary';
+import { RouteAnnouncer } from '../RouteAnnouncer';
+import { DesignSystemLabels } from '../DesignSystemLabels';
+/**
+ * Warns when more than one plugin contributes a `layout`.
+ *
+ * Only the first survives — `find(Boolean)` below — and the loser is whichever
+ * plugin happens to be registered later, which is a decision nobody made. The
+ * shell's layout is what composes identity's `RequireAuth`, so losing it does
+ * not merely change the chrome: every private route renders **ungated**, with
+ * the sidebar, the skip link and the `<main>` landmark gone with it. The host
+ * cannot pick a winner for the app — it has no way to know which layout was
+ * meant — but it can refuse to do it silently.
+ */
+/** The locale every descriptor's `defaultMessage` is authored in. */
+const DEFAULT_LOCALE = 'en';
+/**
+ * Language subtags whose script is written right-to-left, used when the runtime
+ * cannot say.
+ *
+ * A fallback for `Intl.Locale`'s text-info API, which is recent enough that a
+ * browser in the support window may not have it. Deliberately a short list of
+ * the languages an admin UI is plausibly translated into rather than every RTL
+ * script in Unicode: a wrong `dir` is worse than a missing one, and anything not
+ * listed simply gets the correct `ltr` it had before.
+ */
+const RTL_LANGUAGES = new Set([
+    'ar',
+    'arc',
+    'ckb',
+    'dv',
+    'fa',
+    'he',
+    'ks',
+    'ps',
+    'sd',
+    'ug',
+    'ur',
+    'yi'
+]);
+/**
+ * The writing direction of `locale`, for `<html dir>`.
+ *
+ * Nothing was setting it, so every `ml-`/`mr-`/`pl-`/`pr-` in the admin was a
+ * physical direction with no chance of mirroring, and a bidi run truncated the
+ * wrong end of a string at 320px (WCAG 1.3.2, 1.4.10 — `ORT-86`). Setting the
+ * attribute is the host's half and the prerequisite for the rest: a component
+ * that wants to mirror has nothing to mirror *against* until the document
+ * declares a direction.
+ *
+ * **This is the UI locale, not the content locale.** A content surface showing
+ * an Arabic entry inside a German admin is two directions on one page, and the
+ * per-field `dir` the entry editor already sets is what resolves that — the
+ * document says which way the *chrome* runs.
+ */
+function directionOf(locale) {
+    try {
+        const info = new Intl.Locale(locale);
+        const direction = info.getTextInfo?.().direction ?? info.textInfo?.direction;
+        if (direction === 'rtl' || direction === 'ltr')
+            return direction;
+        const language = new Intl.Locale(locale).language;
+        return RTL_LANGUAGES.has(language) ? 'rtl' : 'ltr';
+    }
+    catch {
+        // An unparseable tag is the caller's bug, reported by the `IntlProvider`
+        // rather than here. Left-to-right is what the document already said.
+        return 'ltr';
+    }
+}
+function warnOnLayoutCollision(plugins) {
+    const contributors = plugins
+        .filter((plugin) => plugin.layout)
+        .map((plugin) => plugin.name);
+    if (contributors.length < 2)
+        return;
+    const [winner, ...ignored] = contributors;
+    console.warn(`[bootstrap-admin] ${contributors.length} plugins contribute a layout; only the first is mounted. ` +
+        `Using "${winner}", ignoring ${ignored.map((name) => `"${name}"`).join(', ')}. ` +
+        'Every non-public route renders inside the winner, so if it is not the app shell they are no longer gated.');
+}
+/**
+ * Warns when two routes claim the same `path`.
+ *
+ * React Router matches by rank, not by declaration, so which element renders at
+ * a duplicated path is unspecified; React additionally logs a bare
+ * "two children with the same key" that names the path but not the plugins
+ * behind it. Naming them here is the difference between a five-minute fix and
+ * an afternoon.
+ */
+function warnOnRouteCollisions(plugins) {
+    const owners = new Map();
+    for (const plugin of plugins) {
+        for (const route of plugin.routes ?? []) {
+            owners.set(route.path, [
+                ...(owners.get(route.path) ?? []),
+                plugin.name
+            ]);
+        }
+    }
+    for (const [path, contributors] of owners) {
+        if (contributors.length < 2)
+            continue;
+        console.warn(`[bootstrap-admin] route "${path}" is contributed by ${contributors
+            .map((name) => `"${name}"`)
+            .join(', ')}; only one of them will ever render.`);
+    }
+}
+/**
+ * Reports a missing translation once per message id, per locale.
+ *
+ * `IntlProvider` logs every `MISSING_TRANSLATION` at `error` level, once per
+ * render of every descriptor — 460 of them on a single `/activity` load with
+ * `locale: 'de'` — and gives the host no way to downgrade, sample or collect
+ * them. The volume is not a style complaint: it buries anything real in the
+ * console, which is the only place a developer looks (`ORT-141`).
+ *
+ * Two rules. A locale that *is* the default has nothing to be missing, so the
+ * fallback is the expected path and says nothing at all. Otherwise each id is
+ * reported once, at `warn` — a missing catalogue entry is a gap to fill, not a
+ * failure of this render — and everything that is not a missing translation is
+ * passed through untouched, because those are real formatting errors.
+ */
+function makeIntlErrorHandler(locale, defaultLocale) {
+    const reported = new Set();
+    return (error) => {
+        const code = error.code;
+        if (code !== 'MISSING_TRANSLATION') {
+            console.error(error);
+            return;
+        }
+        if (locale === defaultLocale)
+            return;
+        const id = error
+            .descriptor?.id;
+        const key = id ?? error.message;
+        if (reported.has(key))
+            return;
+        reported.add(key);
+        console.warn(`[bootstrap-admin] no "${locale}" translation for "${key}"; using the default message.`);
+    };
+}
+/**
+ * Bootstraps the Ortha CMS admin app: mounts the React root, wraps it in
+ * the data, i18n, and router providers, and renders the routes contributed by
+ * every plugin.
+ *
+ * Plugins author user-facing strings with `react-intl` (`defineMessages` +
+ * `useIntl`), so the host provides a single `IntlProvider`. Messages are
+ * resolved from each descriptor's `defaultMessage`; a translation catalogue
+ * can be wired in here later without touching plugins.
+ *
+ * Server state is fetched with TanStack Query, so the host also provides one
+ * `QueryClient`. Plugins call `useQuery`/`useMutation` (e.g. identity's
+ * `useLoginMutation`) without owning a client of their own.
+ *
+ * Routes split by `public`: public routes mount as top-level siblings, while
+ * every other route mounts under a single pathless parent that renders the
+ * `layout` a plugin contributed (or a bare `<Outlet/>`). The host is
+ * auth-agnostic — it does not know that `layout` may wrap its children in a
+ * gate; the contributing plugin (the shell) owns that. A `public:false` route
+ * with no gating `layout` therefore renders ungated.
+ */
+export function createAdmin(options) {
+    const { plugins, rootElement = 'root', locale = 'en' } = options;
+    // The document's language, which nothing was setting: `apps/admin/index.html`
+    // ships `lang="en"` and the host never touched it, so a `locale: 'de'` app
+    // was German content announced with an English synthesizer — WCAG 3.1.1
+    // Language of Page, and the one part of `ORT-141` that is unambiguously the
+    // host's to fix. Set before render so assistive tech sees it with the first
+    // paint rather than after a reconciliation.
+    document.documentElement.lang = locale;
+    document.documentElement.dir = directionOf(locale);
+    warnOnLayoutCollision(plugins);
+    warnOnRouteCollisions(plugins);
+    const routes = plugins.flatMap((plugin) => plugin.routes ?? []);
+    const publicRoutes = routes.filter((route) => route.public);
+    const privateRoutes = routes.filter((route) => !route.public);
+    // Wire every plugin's slot contributions into their target slots before
+    // render, so consumers (e.g. the shell toolbar) see all contributed items.
+    for (const plugin of plugins) {
+        for (const contribution of plugin.slots ?? []) {
+            contribution.slot._register(contribution.items);
+        }
+    }
+    // The single layout that wraps every private route; falls back to a bare
+    // outlet before any layout plugin (the shell) is registered.
+    const layout = plugins.map((plugin) => plugin.layout).find(Boolean) ?? (_jsx(Outlet, {}));
+    // Checked rather than cast. `createRoot(null)` throws deep inside React with
+    // a message about a "target container", which is true but says nothing about
+    // *which* id the host was told to mount into — and the page the developer is
+    // looking at is blank either way, so the console is all they have.
+    const container = document.getElementById(rootElement);
+    if (!container) {
+        throw new Error(`[bootstrap-admin] no element with id "${rootElement}" to mount into. ` +
+            'The host HTML must contain it (see `apps/admin/index.html`), or pass a different `rootElement` to createAdmin().');
+    }
+    const root = ReactDOM.createRoot(container);
+    root.render(_jsx(StrictMode, { children: _jsx(AppearanceProvider, { children: _jsx(QueryClientProvider, { client: queryClient, children: _jsx(IntlProvider, { locale: locale, defaultLocale: DEFAULT_LOCALE, onError: makeIntlErrorHandler(locale, DEFAULT_LOCALE), children: _jsx(DesignSystemLabels, { children: _jsxs(TooltipProvider, { delayDuration: 200, children: [_jsx(AppErrorBoundary, { children: _jsxs(BrowserRouter, { children: [_jsx(RouteAnnouncer, {}), _jsx(UnsavedChangesGuard, { children: _jsxs(Routes, { children: [publicRoutes.map((route) => (_jsx(Route, { path: route.path, element: route.element }, route.path))), _jsxs(Route, { element: layout, children: [privateRoutes.map((route) => (_jsx(Route, { path: route.path, element: route.element }, route.path))), _jsx(Route, { path: "*", element: _jsx(Navigate, { to: "/", replace: true }) })] })] }) })] }) }), _jsx(Toaster, {})] }) }) }) }) }) }));
+}

package/dist/lib/types/adminPlugin/index.d.ts

@@ -0,0 +1,66 @@
+import type { ReactNode } from 'react';
+import type { SlotContribution } from '@orthacms/utils-admin';
+/** A route a plugin mounts into the app router. */
+export type RouteItem = {
+    /** Route path (e.g. "/users/*"). */
+    path: string;
+    /** Element rendered at that path. */
+    element: ReactNode;
+    /**
+     * When `true`, the route mounts as a top-level sibling (e.g. the sign-in
+     * page). Omitted/`false` means it mounts under the contributed `layout`.
+     * The host attaches no auth meaning to this — whether "under the layout"
+     * means "gated" is up to the layout (the shell wraps it in identity's
+     * `RequireAuth`).
+     */
+    public?: boolean;
+};
+/**
+ * Contract every admin-side plugin must implement: a name, the routes it
+ * contributes, and optionally the layout its non-`public` siblings render
+ * inside.
+ */
+export type AdminPlugin = {
+    /** Unique identifier. */
+    name: string;
+    /** Routes this plugin contributes. */
+    routes?: RouteItem[];
+    /**
+     * The app shell — chrome that renders an `<Outlet/>`. The host mounts the
+     * first plugin-provided `layout` as the single parent of every non-`public`
+     * route. The host treats it as opaque; the shell plugin composes its auth
+     * provider + gate inside it. Omitted by most plugins.
+     */
+    layout?: ReactNode;
+    /**
+     * Slot contributions (e.g. toolbar nav items). The host wires these into
+     * their target slots before render and attaches no meaning beyond wiring —
+     * the consuming plugin (the shell) defines and reads the slot.
+     */
+    slots?: SlotContribution[];
+};
+/** Options for {@link createAdmin}. */
+export type CreateAdminOptions = {
+    /** Plugins to register. */
+    plugins: AdminPlugin[];
+    /** DOM element id to mount into. Defaults to "root". */
+    rootElement?: string;
+    /**
+     * Active locale for `react-intl`, and the value written to `<html lang>`.
+     * Defaults to `'en'`.
+     *
+     * **It does not translate anything yet.** The admin ships exactly one
+     * catalogue — the `defaultMessage` on each descriptor — and no `messages`
+     * are passed to `IntlProvider`, so every string resolves to its English
+     * default whatever this is set to. What *does* follow it is `Intl`
+     * formatting (dates, numbers, plurals) and the document language, which is
+     * why setting it is still better than not.
+     *
+     * It is typed `string` rather than a union of shipped locales because there
+     * is no set of shipped locales to name yet; when catalogues land, this
+     * should narrow so the option cannot promise something it does not do
+     * (`ORT-141`).
+     */
+    locale?: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/types/adminPlugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/types/adminPlugin/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG;IACpB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,EAAE,SAAS,CAAC;IACnB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACtB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC9B,CAAC;AAEF,uCAAuC;AACvC,MAAM,MAAM,kBAAkB,GAAG;IAC7B,2BAA2B;IAC3B,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC"}

package/dist/lib/types/adminPlugin/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@orthacms/bootstrap-admin",
+    "version": "0.0.0-reserve.0",
+    "description": "@orthacms/bootstrap-admin — part of Ortha CMS.",
+    "license": "MIT",
+    "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/bootstrap/admin",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ortha-source/ortha-cms.git",
+        "directory": "packages/bootstrap/admin"
+    },
+    "bugs": {
+        "url": "https://github.com/ortha-source/ortha-cms/issues"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@orthacms/design-system": "^0.0.1",
+        "@orthacms/utils-admin": "^0.0.1",
+        "@tanstack/react-query": "^5.0.0",
+        "react-intl": "^7.0.0",
+        "tslib": "^2.3.0"
+    },
+    "peerDependencies": {
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+        "react-router-dom": "^6.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}