@fikar-ai/design-react 1.5.0

package/README.md

@@ -0,0 +1,122 @@
+# @fikar-ai/design-react
+
+React components for the Fikar Ink design language. It provides `AppShell`, `NavItem`, `NavHeading`, `BrandLogo`, `AppLauncher`, `ThemeMenu`, `UserMenu`, `UserMenuItem`, `userInitials`, `SearchBox`, `SearchResults`, `FilterChip`, `EntityBadge`, `DetailPanel`, `DetailSection`, `ListRow`, `DaySeparator`, `StatusBadge`, `RelativeTime`, `formatRelative`, `formatExact`, `useShortcut` and `useAppShell`. `AppShell` renders the canonical app shell from `@fikar-ai/design` (`recipes/shell.html`), or the no-sidebar shell (`recipes/shell-no-sidebar.html`) with `sidebar={false}`, and owns the drawer, the desktop collapse and the rail tooltips.
+
+The package ships no CSS. All styling comes from the class names in `@fikar-ai/design/components.css`, so import that too. It releases at the same version as `@fikar-ai/design`. What a version number promises, and how things are deprecated and removed, is in the "Versioning" and "Retiring something" sections of the root README (`@fikar-ai/design`).
+
+Peer ranges: `@fikar-ai/design` `>=1.0.0 <2` (optional, because this package publishes after the CSS package), `react` and `react-dom` `^18.3.0`, `@radix-ui/react-tooltip` `>=1.1.6 <2`.
+
+```sh
+npm install @fikar-ai/design-react @fikar-ai/design @radix-ui/react-tooltip react react-dom
+```
+
+```css
+@import '@fikar-ai/design/tokens.css';
+@import '@fikar-ai/design/components.css';
+```
+
+```tsx
+import { AppShell, NavHeading, NavItem } from '@fikar-ai/design-react';
+import { Link } from 'react-router-dom';
+
+<AppShell
+  brand={<img src={logo} alt="" />}
+  brandName="FIKAR"
+  nav={
+    <>
+      <NavHeading>Workspace</NavHeading>
+      <NavItem component={Link} to="/" icon={<HomeIcon />} label="Home" active={pathname === '/'} />
+      <NavItem component={Link} to="/settings" icon={<GearIcon />} label="Settings" badge="New" active={pathname === '/settings'} />
+    </>
+  }
+  footer={<AccountBlock />}
+  headerActions={<><AppLauncher apps={apps} currentId="platform" /><ThemeMenu value={theme} onChange={setTheme} /><UserMenu email={user.email} signOut={{ href: signOutUrl }} /></>}
+>
+  <Outlet />
+</AppShell>
+```
+
+## API
+
+`AppShell` props: `brand`, `brandName`, `navLabel` (default "Main"), `nav`, `navRail`, `navScroll`, `footer`, `headerStart`, `headerActions`, `children`, `fill` (default `false`), `sidebar` (default `true`), `collapsed`, `defaultCollapsed`, `onCollapsedChange`.
+
+The props are a union on `sidebar`. With the sidebar (the default) `nav` is required. With `sidebar={false}` the shell is a top bar and the content, and `nav`, `navRail`, `navScroll`, `footer`, `navLabel`, `collapsed`, `defaultCollapsed` and `onCollapsedChange` are `never`, so passing one is a type error. `sidebar` must be the literal `true` or `false`. In that mode the component reads and writes no storage, renders no drawer, and `useAppShell()` returns `collapsed: false`, `drawerOpen: false`, `isRail: false` with setters that do nothing. `headerStart` is worth using there: it sits between the brand and the cluster, and scrolls sideways inside itself when the bar is short of room, so the page does not widen and no link is lost.
+
+```tsx
+<AppShell sidebar={false} brand={<BrandLogo lightSrc={light} darkSrc={dark} />} brandName="FIKAR" headerStart={<AdminLinks />} headerActions={<Cluster />}>
+  <Outlet />
+</AppShell>
+```
+
+`footer` is optional. Without it `AppShell` renders no `.side-foot`, so there is no bare divider above the collapse control. `fill` makes the shell one viewport tall at every width with a padless content column, for a page that scrolls inside itself (a conversation with a docked composer).
+
+`BrandLogo` props: `lightSrc`, `darkSrc` (both required strings), `alt` (default `""`, given to both images) and `height` (number of px, inline style on both, absent by default so the package's 18px applies). It renders `<img class="logo-light">` and `<img class="logo-dark">`; the package CSS shows the one that matches the theme (`.dark` or `[data-theme='dark']` on an ancestor), and the classes only take effect inside `.brand`, so use it in the `brand` slot. `brand` itself stays a free slot: if you render your own logo, put `logo-light` and `logo-dark` on the two elements, `<img>` or inline `<svg>`. The old wrapper spans are not needed.
+
+`NavItem` props: `label`, `icon`, `badge`, `active`, `variant` (`'default' | 'back'`, default `'default'`), `component` (default `a`), plus every prop the component accepts except `className` and `children`. `variant="back"` adds `nav-item-back`, the quieter link that leads out of this surface back to where the person came from; put it first. There is no `className` passthrough on purpose (KAN-311). It always renders a plain string `className`. Pass the router's `Link` as `component` and compute `active` in the app; NavLink manages its own class and `aria-current`, which fights the prop. A click closes the drawer.
+
+`NavHeading` takes children and renders a group heading between nav items.
+
+`useAppShell()` returns `{ collapsed, setCollapsed, drawerOpen, setDrawerOpen, isRail }` for content inside the shell. `isRail` is true only while the rail is showing (collapsed and at least 1024px wide). `brandName` is separate from `brand` because the wordmark must sit inside `.brand` for the rail to hide it. `headerStart` fills the top bar left of the cluster, and `navScroll` makes a long nav scroll inside the sidebar.
+
+The collapsed choice is stored in `localStorage` under `fikar.shell.collapsed` (`"1"` collapsed, `"0"` or absent open) unless you control it with `collapsed`. `@fikar-ai/design/shell.js` writes the same values since 0.8.0.
+
+Also new in 0.8.0 in the CSS, no React API needed: `.rail-hidden` and `.rail-only` for content that shows only open or only in the rail (`.rail-hidden` also leaves the tab order and the accessibility tree, so a list of links can go in it), and a fix that keeps a closed drawer out of the tab order. Upgrading from 0.7: the footer identity rule now matches direct children of `.meta`, so a plan pill in a nested span no longer needs a forced colour; the top bar and main area may shrink below their content; and an omitted `footer` renders no `.side-foot`. Full guide: the "React apps" section of the `@fikar-ai/design` README.
+
+## Theme menu (since 1.2.0)
+
+`ThemeMenu` is the sun or moon button and the panel of Light, Dark and System, for the second slot of the shell cluster. It renders `recipes/theme-menu.html` and needs `@fikar-ai/design` 1.2.0 or later for its CSS, so install both at the same version. It keeps no state and stores nothing. The app passes the theme it has and a handler, and applies and saves the choice in its own way.
+
+```tsx
+import { ThemeMenu } from '@fikar-ai/design-react';
+
+<ThemeMenu value={theme} onChange={(next) => { applyTheme(next); saveTheme(next); }} />
+```
+
+`value` is `'light'`, `'dark'` or `'system'`, and the chosen row follows it. `onChange` is called with the row the person chose, unless it is the one already chosen. The sun or moon on the button comes from the theme on the root (`.dark` or `[data-theme='dark']`) in the CSS, so it is right on first paint and the component takes no theme for it. It opens on click and closes on Escape, on a press outside and on choosing a row, and the arrow keys move between the rows. The markup and behaviour are documented under "Theme menu" in the `@fikar-ai/design` README.
+
+## User menu (since 1.1.0)
+
+`UserMenu` is the avatar and account panel for the last slot of the shell cluster. It renders `recipes/user-menu.html` and needs `@fikar-ai/design` 1.1.0 or later for its CSS, so install both at the same version. It opens on click and closes on Escape, on a press outside and on choosing a row, with no extra dependency.
+
+```tsx
+import { UserMenu, UserMenuItem } from '@fikar-ai/design-react';
+import { Link } from 'react-router-dom';
+
+<UserMenu
+  name={user.name}
+  email={user.email}
+  avatarUrl={user.avatarUrl}
+  accountSettings={{ component: Link, to: '/account' }}
+  signOut={{ onSelect: () => { clearLocalState(); signOut(); } }}
+>
+  <UserMenuItem component={Link} to="/workspace">Workspace settings</UserMenuItem>
+</UserMenu>
+```
+
+`signOut` takes `{ href }` or `{ onSelect }`. Leave out `accountSettings` to omit that row. `userInitials(name, email)` is the rule for the initials. The props, the markup and the behaviour are documented under "User menu" in the `@fikar-ai/design` README.
+
+## App launcher (since 1.2.0)
+
+`AppLauncher` is the grid button and app list for the first slot of the shell cluster. It renders `recipes/launcher.html` and needs `@fikar-ai/design` 1.2.0 or later for the focus ring on its button, so install both at the same version. It opens on click and closes on Escape, on a press outside and on choosing an app, with no extra dependency. It fetches nothing, and it renders nothing when `apps` is empty.
+
+```tsx
+import { AppLauncher } from '@fikar-ai/design-react';
+
+<AppLauncher
+  apps={[
+    { id: 'chat', name: 'Chat', url: 'https://chat.fikar.ai', hint: "Ask across your organization's memory" },
+    { id: 'platform', name: 'Platform', url: 'https://platform.fikar.ai' },
+  ]}
+  currentId="chat"
+/>
+```
+
+Each app has `id`, `name`, `url` and an optional `hint`. The launcher is a grid of tiles, a glyph picked by `id` over the name, and the hint is not shown. The app whose `id` is `currentId` gets `.current` and `aria-current="page"`. The rows are plain links, because they leave the app. The props, the markup and the behaviour are documented under "App launcher recipe" in the `@fikar-ai/design` README.
+
+## Search
+
+`SearchBox` (a controlled search input with an icon, a clear button and a shortcut hint, in a `'bar'` or `'panel'` size), `SearchResults` (the typeahead listbox, which hears ArrowDown, ArrowUp, Enter and Escape on the input), `FilterChip` (a toggle pill with `pressed` and `onToggle`), `EntityBadge` (`type` is `'PERSON'`, `'ORGANIZATION'`, `'EVENT'` or `'GEO'`) and `useShortcut(keys, handler)` (`'/'` and `'mod+k'`, the React counterpart of what `shell.js` binds). Each renders a recipe from `@fikar-ai/design` (`search.html`, `search-results.html`, `filter-chip.html`, `entity-badge.html`) and adds no styling of its own. `SearchBox` forwards its ref to the input and never renders `data-fk-search`, so the app registers the shortcut with `useShortcut`. The props, an example and the drift check rule are in the root README under "Search".
+
+## Detail panel, list rows, status badges and relative time
+
+`DetailPanel` (a type line with a dot, a serif title, a description and an optional close button) with `DetailSection` (a heading over rows or chips), `ListRow` (a title and a muted line, a button by default and a link with `component`) with `DaySeparator`, `StatusBadge` (`status` is `'success'`, `'warning'`, `'destructive'` or `'muted'`, and the word is the children) and `RelativeTime` (a `<time>` that says "4 h ago" and keeps the exact time in its title, refreshing itself while mounted). `formatRelative(value, now?)` and `formatExact(value, now?)` are the same wording as `FikarShell.formatRelative` in `shell.js`. Each component renders a recipe from `@fikar-ai/design` (`detail-panel.html`, `list-row.html`, `status-badge.html`, `time.html`) and adds no styling of its own. The props, the wording rules, the placement of the panel and what each app changes to adopt them are in the root README under "Detail panel, list row, status badge and relative time".

package/dist/app-icons.d.ts

@@ -0,0 +1,2 @@
+/** The inner markup of each app's launcher glyph, keyed by app id. Each is drawn in the shared 24px, 1.5 stroke frame. */
+export declare const APP_ICONS: Readonly<Record<string, string>>;

package/dist/app-icons.js

@@ -0,0 +1,11 @@
+// Generated by scripts/build-app-icons.mjs from brand/apps/*.svg. Do not edit; change the SVG and run the script.
+/** The inner markup of each app's launcher glyph, keyed by app id. Each is drawn in the shared 24px, 1.5 stroke frame. */
+export const APP_ICONS = {
+    "account": "<circle cx=\"12\" cy=\"8\" r=\"5\"/><path d=\"M20 21a8 8 0 0 0-16 0\"/>",
+    "chat": "<path d=\"M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z\"/>",
+    "cost-calculator": "<rect width=\"16\" height=\"20\" x=\"4\" y=\"2\" rx=\"2\"/><line x1=\"8\" x2=\"16\" y1=\"6\" y2=\"6\"/><line x1=\"16\" x2=\"16\" y1=\"14\" y2=\"18\"/><path d=\"M16 10h.01\"/><path d=\"M12 10h.01\"/><path d=\"M8 10h.01\"/><path d=\"M12 14h.01\"/><path d=\"M8 14h.01\"/><path d=\"M12 18h.01\"/><path d=\"M8 18h.01\"/>",
+    "crs": "<circle cx=\"12\" cy=\"4.5\" r=\"2.5\"/><path d=\"m10.2 6.3-3.9 3.9\"/><circle cx=\"4.5\" cy=\"12\" r=\"2.5\"/><path d=\"M7 12h10\"/><circle cx=\"19.5\" cy=\"12\" r=\"2.5\"/><path d=\"m13.8 17.7 3.9-3.9\"/><circle cx=\"12\" cy=\"19.5\" r=\"2.5\"/>",
+    "dictionary": "<path d=\"M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20\"/><path d=\"m8 13 4-7 4 7\"/><path d=\"M9.1 11h5.7\"/>",
+    "platform": "<line x1=\"21\" x2=\"14\" y1=\"4\" y2=\"4\"/><line x1=\"10\" x2=\"3\" y1=\"4\" y2=\"4\"/><line x1=\"21\" x2=\"12\" y1=\"12\" y2=\"12\"/><line x1=\"8\" x2=\"3\" y1=\"12\" y2=\"12\"/><line x1=\"21\" x2=\"16\" y1=\"20\" y2=\"20\"/><line x1=\"12\" x2=\"3\" y1=\"20\" y2=\"20\"/><line x1=\"14\" x2=\"14\" y1=\"2\" y2=\"6\"/><line x1=\"8\" x2=\"8\" y1=\"10\" y2=\"14\"/><line x1=\"16\" x2=\"16\" y1=\"18\" y2=\"22\"/>",
+    "super-admin": "<path d=\"M6 22V4a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v18Z\"/><path d=\"M6 12H4a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h2\"/><path d=\"M18 9h2a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-2\"/><path d=\"M10 6h4\"/><path d=\"M10 10h4\"/><path d=\"M10 14h4\"/><path d=\"M10 18h4\"/>",
+};

package/dist/app-launcher.d.ts

@@ -0,0 +1,20 @@
+export interface LauncherApp {
+    id: string;
+    name: string;
+    url: string;
+    /** Accepted so hosts keep passing it. The grid does not show it. */
+    hint?: string;
+}
+export interface AppLauncherProps {
+    /** The apps the person may open, already filtered and ordered by the app. The component fetches nothing. */
+    apps: readonly LauncherApp[];
+    /** The `id` of the app the person is in. That row is marked with `.current` and `aria-current="page"`. */
+    currentId?: string;
+}
+/**
+ * The app launcher for the first slot of the shell cluster. Renders recipes/launcher.html, or nothing when there are no apps.
+ * The apps are a grid of tiles, a glyph over the name.
+ * Opens on click and closes on Escape (focus returns to the button), on a press outside and on choosing an app.
+ * Arrow keys, Home and End move between tiles. The rows are plain links, because they leave the app.
+ */
+export declare function AppLauncher({ apps, currentId }: AppLauncherProps): JSX.Element | null;

package/dist/app-launcher.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { APP_ICONS } from './app-icons.js';
+import { useMenu } from './use-menu.js';
+const GridIcon = () => (_jsxs("svg", { viewBox: "0 0 24 24", fill: "currentColor", "aria-hidden": "true", children: [_jsx("circle", { cx: "5", cy: "5", r: "2" }), _jsx("circle", { cx: "12", cy: "5", r: "2" }), _jsx("circle", { cx: "19", cy: "5", r: "2" }), _jsx("circle", { cx: "5", cy: "12", r: "2" }), _jsx("circle", { cx: "12", cy: "12", r: "2" }), _jsx("circle", { cx: "19", cy: "12", r: "2" }), _jsx("circle", { cx: "5", cy: "19", r: "2" }), _jsx("circle", { cx: "12", cy: "19", r: "2" }), _jsx("circle", { cx: "19", cy: "19", r: "2" })] }));
+// The glyph is the package's, picked by app id. An id it does not know gets the first letter of the name, in the same tile.
+const AppGlyph = ({ app }) => {
+    const body = Object.prototype.hasOwnProperty.call(APP_ICONS, app.id) ? APP_ICONS[app.id] : undefined;
+    return (_jsx("span", { className: "launcher-tile", "aria-hidden": "true", children: body === undefined ? (Array.from(app.name)[0]?.toUpperCase()) : (_jsx("svg", { className: "app-icon", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", 
+            // The body is a constant generated from brand/apps/*.svg, never app data.
+            dangerouslySetInnerHTML: { __html: body } })) }));
+};
+/**
+ * The app launcher for the first slot of the shell cluster. Renders recipes/launcher.html, or nothing when there are no apps.
+ * The apps are a grid of tiles, a glyph over the name.
+ * Opens on click and closes on Escape (focus returns to the button), on a press outside and on choosing an app.
+ * Arrow keys, Home and End move between tiles. The rows are plain links, because they leave the app.
+ */
+export function AppLauncher({ apps, currentId }) {
+    const { open, toggle, root, trigger, rootClassName, moveFocus, closeOnFocusLeave, closeOnRow } = useMenu();
+    if (apps.length === 0)
+        return null;
+    return (_jsxs("div", { ref: root, className: rootClassName, onKeyDown: moveFocus, onBlur: closeOnFocusLeave, children: [_jsx("button", { ref: trigger, className: "launcher-btn", type: "button", "aria-haspopup": "menu", "aria-expanded": open, "aria-label": "Switch app", onClick: toggle, children: _jsx(GridIcon, {}) }), _jsx("div", { className: "launcher-panel launcher-apps", role: "menu", onClick: closeOnRow, children: apps.map((app) => {
+                    const current = app.id === currentId;
+                    return (_jsxs("a", { className: current ? 'launcher-item current' : 'launcher-item', role: "menuitem", href: app.url, "aria-current": current ? 'page' : undefined, children: [_jsx(AppGlyph, { app: app }), app.name] }, app.id));
+                }) })] }));
+}

package/dist/app-shell.d.ts

@@ -0,0 +1,47 @@
+import type { ReactNode } from 'react';
+interface SharedShellProps {
+    /** The logo, usually a BrandLogo or an img from @fikar-ai/design/brand/. Shown in the sidebar and the top bar, or in the top bar alone without a sidebar. */
+    brand?: ReactNode;
+    /** The wordmark text. Hidden by the package CSS in the rail. */
+    brandName?: string;
+    /** Top bar content to the left of the cluster, such as a search box or a page title. Rendered only when given. Without a sidebar it scrolls sideways inside itself when the bar is short of room. */
+    headerStart?: ReactNode;
+    /** Top right cluster: launcher, theme control, avatar, in that order. */
+    headerActions?: ReactNode;
+    children?: ReactNode;
+    /** Fill mode: the shell is one viewport tall at every width and the content area is a padless flex column, for a page that scrolls inside itself. Default false. */
+    fill?: boolean;
+}
+interface SidebarShellProps extends SharedShellProps {
+    /** Default true. Pass `false` for a top bar with no sidebar. */
+    sidebar?: true;
+    /** Accessible name of the sidebar navigation. Default "Main". */
+    navLabel?: string;
+    /** The sidebar navigation. Shown when the sidebar is open, and in the rail when navRail is omitted. */
+    nav: ReactNode;
+    /** The sidebar navigation for the desktop rail. Use it when nav is not a list of links. */
+    navRail?: ReactNode;
+    /** Makes the nav scroll inside the sidebar, for long lists. The foot and the collapse control stay in view. */
+    navScroll?: boolean;
+    /** Content of the sidebar foot, usually the signed-in person. The foot and its divider are not rendered when this is empty. */
+    footer?: ReactNode;
+    /** Controlled collapsed state. When set, storage is not read or written. */
+    collapsed?: boolean;
+    /** Initial state when nothing is stored. Default false. */
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+}
+interface TopbarShellProps extends SharedShellProps {
+    sidebar: false;
+    navLabel?: never;
+    nav?: never;
+    navRail?: never;
+    navScroll?: never;
+    footer?: never;
+    collapsed?: never;
+    defaultCollapsed?: never;
+    onCollapsedChange?: never;
+}
+export type AppShellProps = SidebarShellProps | TopbarShellProps;
+export declare function AppShell(props: AppShellProps): JSX.Element;
+export {};

package/dist/app-shell.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import * as Tooltip from '@radix-ui/react-tooltip';
+import { AppShellContext } from './context.js';
+import { readCollapsed, writeCollapsed } from './storage.js';
+const DESKTOP_QUERY = '(min-width: 1024px)';
+// useLayoutEffect warns during server rendering; the effect body only matters in the browser.
+const useIsoLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+const MenuIcon = () => (_jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", "aria-hidden": "true", children: _jsx("path", { d: "M4 6h16M4 12h16M4 18h16" }) }));
+const ChevronIcon = () => (_jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("path", { d: "M15 6l-6 6 6 6" }) }));
+function SidebarShell({ brand, brandName, navLabel = 'Main', nav, navRail, navScroll = false, footer, headerStart, headerActions, children, fill = false, collapsed: collapsedProp, defaultCollapsed = false, onCollapsedChange, }) {
+    const isControlled = collapsedProp !== undefined;
+    const [innerCollapsed, setInnerCollapsed] = useState(defaultCollapsed);
+    const collapsed = isControlled ? collapsedProp : innerCollapsed;
+    const [drawerOpen, setDrawerOpen] = useState(false);
+    const [desktop, setDesktop] = useState(false);
+    const menuRef = useRef(null);
+    // Storage is read after the first render so server and client markup match.
+    useIsoLayoutEffect(() => {
+        if (isControlled)
+            return;
+        const stored = readCollapsed();
+        if (stored !== null)
+            setInnerCollapsed(stored);
+        // Mount only: later changes come from the toggle, not from storage.
+    }, []);
+    useIsoLayoutEffect(() => {
+        if (typeof window.matchMedia !== 'function')
+            return;
+        const query = window.matchMedia(DESKTOP_QUERY);
+        const sync = () => {
+            setDesktop(query.matches);
+            if (query.matches)
+                setDrawerOpen(false);
+        };
+        sync();
+        query.addEventListener('change', sync);
+        return () => query.removeEventListener('change', sync);
+    }, []);
+    const setCollapsed = useCallback((next) => {
+        if (!isControlled) {
+            setInnerCollapsed(next);
+            writeCollapsed(next);
+        }
+        onCollapsedChange?.(next);
+    }, [isControlled, onCollapsedChange]);
+    const closeDrawer = useCallback(() => {
+        setDrawerOpen(false);
+        menuRef.current?.focus();
+    }, []);
+    useEffect(() => {
+        if (!drawerOpen)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key === 'Escape')
+                closeDrawer();
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [drawerOpen, closeDrawer]);
+    const isRail = collapsed && desktop;
+    const state = useMemo(() => ({ collapsed, setCollapsed, drawerOpen, setDrawerOpen, isRail }), [collapsed, setCollapsed, drawerOpen, isRail]);
+    const shellClass = ['shell', 'with-topbar', fill && 'is-fill', drawerOpen && 'nav-open', collapsed && 'is-collapsed']
+        .filter(Boolean)
+        .join(' ');
+    const brandBlock = (_jsxs(_Fragment, { children: [brand, brandName ? _jsx("span", { className: "word", children: brandName }) : null] }));
+    return (_jsx(AppShellContext.Provider, { value: state, children: _jsx(Tooltip.Provider, { delayDuration: 300, children: _jsxs("div", { className: shellClass, id: "shell", children: [_jsxs("aside", { className: "sidebar", id: "sidebar", children: [_jsxs("div", { className: "brand", children: [brandBlock, _jsx("button", { className: "shell-close iconbtn", type: "button", "aria-label": "Close navigation", onClick: closeDrawer, children: "\u00D7" })] }), _jsx("nav", { className: navScroll ? 'side is-scroll' : 'side', "aria-label": navLabel, children: isRail && navRail !== undefined ? navRail : nav }), footer ? _jsx("div", { className: "side-foot", children: footer }) : null, _jsxs("button", { className: "shell-collapse", type: "button", "aria-controls": "sidebar", "aria-pressed": collapsed, title: collapsed ? 'Expand sidebar' : 'Collapse sidebar', onClick: () => setCollapsed(!collapsed), children: [_jsx(ChevronIcon, {}), _jsx("span", { className: "nav-label", children: "Collapse" })] })] }), _jsxs("header", { className: "shell-topbar", children: [_jsx("button", { ref: menuRef, className: "shell-menu", type: "button", "aria-label": "Open navigation", "aria-controls": "sidebar", "aria-expanded": drawerOpen, onClick: () => setDrawerOpen(true), children: _jsx(MenuIcon, {}) }), _jsx("div", { className: "brand", children: brandBlock }), headerStart ? _jsx("div", { className: "shell-topbar-start", children: headerStart }) : null, _jsx("div", { className: "cluster", children: headerActions })] }), _jsx("div", { className: "shell-scrim", hidden: !drawerOpen, onClick: closeDrawer }), _jsx("main", { className: "main", children: _jsx("div", { className: "content", children: children }) })] }) }) }));
+}
+// No drawer, no rail, no stored choice: the state is fixed, so slot content that reads it
+// gets the answer for an open, full-width layout, and its setters do nothing.
+const NO_SIDEBAR_STATE = {
+    collapsed: false,
+    setCollapsed: () => { },
+    drawerOpen: false,
+    setDrawerOpen: () => { },
+    isRail: false,
+};
+function TopbarShell({ brand, brandName, headerStart, headerActions, children, fill = false }) {
+    return (_jsx(AppShellContext.Provider, { value: NO_SIDEBAR_STATE, children: _jsxs("div", { className: ['shell', 'with-topbar', 'no-sidebar', fill && 'is-fill'].filter(Boolean).join(' '), id: "shell", children: [_jsxs("header", { className: "shell-topbar", children: [_jsxs("div", { className: "brand", children: [brand, brandName ? _jsx("span", { className: "word", children: brandName }) : null] }), headerStart ? _jsx("div", { className: "shell-topbar-start", children: headerStart }) : null, _jsx("div", { className: "cluster", children: headerActions })] }), _jsx("main", { className: "main", children: _jsx("div", { className: "content", children: children }) })] }) }));
+}
+export function AppShell(props) {
+    return props.sidebar === false ? _jsx(TopbarShell, { ...props }) : _jsx(SidebarShell, { ...props });
+}

package/dist/brand-logo.d.ts

@@ -0,0 +1,15 @@
+export interface BrandLogoProps {
+    /** The logo for the light theme, usually @fikar-ai/design/brand/fikar-logo.svg. */
+    lightSrc: string;
+    /** The logo for the dark theme, usually @fikar-ai/design/brand/fikar-logo-reversed.svg. */
+    darkSrc: string;
+    /** Accessible name, given to both images. Only one is ever displayed. Default "", for a logo next to the wordmark. */
+    alt?: string;
+    /** Rendered height in px. Default is the package's 18px. */
+    height?: number;
+}
+/**
+ * Both logo variants as images. The package CSS shows the one that matches the theme, so it belongs in the
+ * shell's `brand` slot: the selectors are `.brand .logo-light` and `.brand .logo-dark`.
+ */
+export declare function BrandLogo({ lightSrc, darkSrc, alt, height }: BrandLogoProps): JSX.Element;

package/dist/brand-logo.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Both logo variants as images. The package CSS shows the one that matches the theme, so it belongs in the
+ * shell's `brand` slot: the selectors are `.brand .logo-light` and `.brand .logo-dark`.
+ */
+export function BrandLogo({ lightSrc, darkSrc, alt = '', height }) {
+    const style = height === undefined ? undefined : { height };
+    return (_jsxs(_Fragment, { children: [_jsx("img", { className: "logo-light", src: lightSrc, alt: alt, style: style }), _jsx("img", { className: "logo-dark", src: darkSrc, alt: alt, style: style })] }));
+}

package/dist/context.d.ts

@@ -0,0 +1,12 @@
+export interface AppShellState {
+    /** True when the desktop rail is the chosen state. It has no visual effect below 1024px. */
+    collapsed: boolean;
+    setCollapsed: (collapsed: boolean) => void;
+    /** True while the drawer below 1024px is open. */
+    drawerOpen: boolean;
+    setDrawerOpen: (open: boolean) => void;
+    /** True only while the rail is actually showing: collapsed and at least 1024px wide. */
+    isRail: boolean;
+}
+export declare const AppShellContext: import("react").Context<AppShellState | null>;
+export declare function useAppShell(): AppShellState;

package/dist/context.js

@@ -0,0 +1,8 @@
+import { createContext, useContext } from 'react';
+export const AppShellContext = createContext(null);
+export function useAppShell() {
+    const state = useContext(AppShellContext);
+    if (!state)
+        throw new Error('useAppShell must be used inside <AppShell>');
+    return state;
+}

package/dist/detail-panel.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+import type { EntityType } from './entity-badge.js';
+export interface DetailPanelProps {
+    /** The type line, in words such as "Person". It is drawn in capitals. */
+    type: string;
+    /** The colour of the dot before the type line, as one of the entity types. Without it the dot is muted. */
+    dot?: EntityType;
+    title: ReactNode;
+    description?: ReactNode;
+    /** Renders the close button, and is called when it is pressed. Without it the panel has no close button. */
+    onClose?: () => void;
+    /** `DetailSection`s, or anything else that belongs in the panel. */
+    children?: ReactNode;
+}
+export interface DetailSectionProps {
+    heading: ReactNode;
+    /** The rows (`.detail-row`) and chips (`.detail-chips`) of the section, as the README shows them. */
+    children: ReactNode;
+}
+/** A section of a DetailPanel: an upper case heading over its rows or chips. */
+export declare function DetailSection({ heading, children }: DetailSectionProps): JSX.Element;
+/**
+ * The panel that describes one thing, from recipes/detail-panel.html. It is the surface only. The page or the app places it, and it fills its container below
+ * 768px. The title names the panel for assistive technology. The dot colours come from the --entity-* roles, so they follow the theme.
+ */
+export declare function DetailPanel({ type, dot, title, description, onClose, children }: DetailPanelProps): JSX.Element;

package/dist/detail-panel.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+/** A section of a DetailPanel: an upper case heading over its rows or chips. */
+export function DetailSection({ heading, children }) {
+    return (_jsxs("section", { className: "detail-section", children: [_jsx("h3", { className: "detail-heading", children: heading }), children] }));
+}
+/**
+ * The panel that describes one thing, from recipes/detail-panel.html. It is the surface only. The page or the app places it, and it fills its container below
+ * 768px. The title names the panel for assistive technology. The dot colours come from the --entity-* roles, so they follow the theme.
+ */
+export function DetailPanel({ type, dot, title, description, onClose, children }) {
+    const titleId = useId();
+    return (_jsxs("aside", { className: "detail-panel", "aria-labelledby": titleId, children: [onClose ? (_jsx("button", { className: "detail-close", type: "button", "aria-label": "Close", onClick: onClose, children: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("path", { d: "M18 6 6 18M6 6l12 12" }) }) })) : null, _jsxs("p", { className: "detail-type", children: [_jsx("i", { className: dot ? `detail-dot detail-dot-${dot.toLowerCase()}` : 'detail-dot', "aria-hidden": "true" }), type] }), _jsx("h2", { className: "detail-title", id: titleId, children: title }), description ? _jsx("p", { className: "detail-desc", children: description }) : null, children] }));
+}

package/dist/entity-badge.d.ts

@@ -0,0 +1,7 @@
+export type EntityType = 'PERSON' | 'ORGANIZATION' | 'EVENT' | 'GEO';
+export interface EntityBadgeProps {
+    /** The entity type as the knowledge graph names it, in upper case. */
+    type: EntityType;
+}
+/** The badge for one of the four entity types. Renders a span from recipes/entity-badge.html, coloured by the --entity-* roles. */
+export declare function EntityBadge({ type }: EntityBadgeProps): JSX.Element;

package/dist/entity-badge.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+const BADGES = {
+    PERSON: { className: 'badge b-person', label: 'Person' },
+    ORGANIZATION: { className: 'badge b-organization', label: 'Organization' },
+    EVENT: { className: 'badge b-event', label: 'Event' },
+    GEO: { className: 'badge b-geo', label: 'Geo' },
+};
+/** The badge for one of the four entity types. Renders a span from recipes/entity-badge.html, coloured by the --entity-* roles. */
+export function EntityBadge({ type }) {
+    const { className, label } = BADGES[type];
+    return _jsx("span", { className: className, children: label });
+}

package/dist/filter-chip.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+export interface FilterChipProps {
+    /** Whether the filter is on. It is the chip's only state, so the chip follows this. */
+    pressed: boolean;
+    /** Called with the state the person asked for, the opposite of `pressed`. */
+    onToggle: (pressed: boolean) => void;
+    children: ReactNode;
+}
+/** A filter chip: a toggle button styled as a pill. Renders a button from recipes/filter-chip.html, and `aria-pressed` is what the CSS draws. */
+export declare function FilterChip({ pressed, onToggle, children }: FilterChipProps): JSX.Element;

package/dist/filter-chip.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** A filter chip: a toggle button styled as a pill. Renders a button from recipes/filter-chip.html, and `aria-pressed` is what the CSS draws. */
+export function FilterChip({ pressed, onToggle, children }) {
+    return (_jsx("button", { className: "pill p-toggle", type: "button", "aria-pressed": pressed, onClick: () => onToggle(!pressed), children: children }));
+}

package/dist/format-time.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The moment as "22 Sep, 08:16": day, month, then the time on a 24 hour clock, in the reader's time zone. From a year away, in the past or ahead, the year is
+ * there too ("22 Sep 2025, 08:16"). The month names are written out because Intl gives "Sept" for September in en-GB. A value that is not a date gives an empty string.
+ */
+export declare function formatExact(value: Date | string, now?: Date): string;
+/**
+ * "just now" under a minute, "4 min ago" under an hour and "4 h ago" under a day, then formatExact. A moment up to a minute ahead is "just now", since a clock a
+ * few seconds fast is common, and one further ahead is a date and not an age, so it is given exactly. `now` is for tests and defaults to the current time.
+ */
+export declare function formatRelative(value: Date | string, now?: Date): string;

package/dist/format-time.js

@@ -0,0 +1,35 @@
+// The one wording for a moment, the same as shell.js gives a plain page (FikarShell.formatRelative). Both are tested against test/fixtures/time-rules.json.
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const MINUTE = 60000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const YEAR = 365 * DAY;
+const two = (n) => String(n).padStart(2, '0');
+/**
+ * The moment as "22 Sep, 08:16": day, month, then the time on a 24 hour clock, in the reader's time zone. From a year away, in the past or ahead, the year is
+ * there too ("22 Sep 2025, 08:16"). The month names are written out because Intl gives "Sept" for September in en-GB. A value that is not a date gives an empty string.
+ */
+export function formatExact(value, now = new Date()) {
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return '';
+    const year = Math.abs(now.getTime() - date.getTime()) >= YEAR ? ` ${date.getFullYear()}` : '';
+    return `${date.getDate()} ${MONTHS[date.getMonth()]}${year}, ${two(date.getHours())}:${two(date.getMinutes())}`;
+}
+/**
+ * "just now" under a minute, "4 min ago" under an hour and "4 h ago" under a day, then formatExact. A moment up to a minute ahead is "just now", since a clock a
+ * few seconds fast is common, and one further ahead is a date and not an age, so it is given exactly. `now` is for tests and defaults to the current time.
+ */
+export function formatRelative(value, now = new Date()) {
+    const time = new Date(value).getTime();
+    if (Number.isNaN(time))
+        return '';
+    const age = now.getTime() - time;
+    if (age < -MINUTE || age >= DAY)
+        return formatExact(value, now);
+    if (age < MINUTE)
+        return 'just now';
+    if (age < HOUR)
+        return `${Math.floor(age / MINUTE)} min ago`;
+    return `${Math.floor(age / HOUR)} h ago`;
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+export { AppShell } from './app-shell.js';
+export type { AppShellProps } from './app-shell.js';
+export { BrandLogo } from './brand-logo.js';
+export type { BrandLogoProps } from './brand-logo.js';
+export { NavItem, NavHeading } from './nav-item.js';
+export type { NavItemProps } from './nav-item.js';
+export { useAppShell } from './context.js';
+export type { AppShellState } from './context.js';
+export { AppLauncher } from './app-launcher.js';
+export type { AppLauncherProps, LauncherApp } from './app-launcher.js';
+export { ThemeMenu } from './theme-menu.js';
+export type { ThemeMenuProps, ThemeChoice } from './theme-menu.js';
+export { UserMenu, UserMenuItem } from './user-menu.js';
+export type { UserMenuProps, UserMenuItemProps, UserMenuLinkProps, UserMenuSignOut } from './user-menu.js';
+export { userInitials } from './user-initials.js';
+export { SearchBox } from './search-box.js';
+export type { SearchBoxProps } from './search-box.js';
+export { SearchResults } from './search-results.js';
+export type { SearchResultsProps, SearchResultItem } from './search-results.js';
+export { FilterChip } from './filter-chip.js';
+export type { FilterChipProps } from './filter-chip.js';
+export { EntityBadge } from './entity-badge.js';
+export type { EntityBadgeProps, EntityType } from './entity-badge.js';
+export { useShortcut } from './use-shortcut.js';
+export { DetailPanel, DetailSection } from './detail-panel.js';
+export type { DetailPanelProps, DetailSectionProps } from './detail-panel.js';
+export { ListRow, DaySeparator } from './list-row.js';
+export type { ListRowProps } from './list-row.js';
+export { StatusBadge } from './status-badge.js';
+export type { StatusBadgeProps } from './status-badge.js';
+export { RelativeTime } from './relative-time.js';
+export type { RelativeTimeProps } from './relative-time.js';
+export { formatRelative, formatExact } from './format-time.js';

package/dist/index.js

@@ -0,0 +1,18 @@
+export { AppShell } from './app-shell.js';
+export { BrandLogo } from './brand-logo.js';
+export { NavItem, NavHeading } from './nav-item.js';
+export { useAppShell } from './context.js';
+export { AppLauncher } from './app-launcher.js';
+export { ThemeMenu } from './theme-menu.js';
+export { UserMenu, UserMenuItem } from './user-menu.js';
+export { userInitials } from './user-initials.js';
+export { SearchBox } from './search-box.js';
+export { SearchResults } from './search-results.js';
+export { FilterChip } from './filter-chip.js';
+export { EntityBadge } from './entity-badge.js';
+export { useShortcut } from './use-shortcut.js';
+export { DetailPanel, DetailSection } from './detail-panel.js';
+export { ListRow, DaySeparator } from './list-row.js';
+export { StatusBadge } from './status-badge.js';
+export { RelativeTime } from './relative-time.js';
+export { formatRelative, formatExact } from './format-time.js';

package/dist/list-row.d.ts

@@ -0,0 +1,22 @@
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+interface ListRowOwnProps {
+    title: ReactNode;
+    /** The muted line under the title. It can hold a `RelativeTime`. */
+    meta?: ReactNode;
+    /** The row the page is on. It is drawn from `aria-current`, "page" on a link and "true" on a button. */
+    active?: boolean;
+}
+export type ListRowProps<C extends ElementType = 'button'> = ListRowOwnProps & {
+    /** The element or router link to render. A button by default. Pass "a" with `href`, or the router's Link with `to`. It must forward its ref and accept a string className. */
+    component?: C;
+} & Omit<ComponentPropsWithoutRef<C>, keyof ListRowOwnProps | 'component' | 'className' | 'children'>;
+/**
+ * A row in a list, from recipes/list-row.html: a title and a muted line under it. A button that selects by default, so `onClick` is the handler, and a link
+ * when `component` is a link. Every other prop, such as `href`, `to` or `onClick`, goes to that element.
+ */
+export declare function ListRow<C extends ElementType = 'button'>({ title, meta, active, component, ...rest }: ListRowProps<C>): JSX.Element;
+/** The label that starts a day's rows in a list, from recipes/list-row.html. The page decides the groups and their words. It is an h3, so put it under a heading of the list. */
+export declare function DaySeparator({ label }: {
+    label: string;
+}): JSX.Element;
+export {};

package/dist/list-row.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A row in a list, from recipes/list-row.html: a title and a muted line under it. A button that selects by default, so `onClick` is the handler, and a link
+ * when `component` is a link. Every other prop, such as `href`, `to` or `onClick`, goes to that element.
+ */
+export function ListRow({ title, meta, active = false, component, ...rest }) {
+    const Component = component ?? 'button';
+    const isButton = Component === 'button';
+    return (_jsxs(Component, { type: isButton ? 'button' : undefined, ...rest, className: "list-row", "aria-current": active ? (isButton ? 'true' : 'page') : undefined, children: [_jsx("span", { className: "list-row-title", children: title }), meta ? _jsx("span", { className: "list-row-meta", children: meta }) : null] }));
+}
+/** The label that starts a day's rows in a list, from recipes/list-row.html. The page decides the groups and their words. It is an h3, so put it under a heading of the list. */
+export function DaySeparator({ label }) {
+    return _jsx("h3", { className: "day-sep", children: label });
+}