@broberg/app-shell 0.1.0

package/dist/preact.d.ts

@@ -0,0 +1,254 @@
+import { ComponentChildren, JSX } from 'preact';
+import { NotificationRow } from '@broberg/notifications/types';
+export { NotificationRow } from '@broberg/notifications/types';
+
+/** One sidebar entry. `icon` is whatever your framework renders (an element). */
+interface NavItem<Icon = unknown> {
+    id: string;
+    label: string;
+    href: string;
+    icon?: Icon;
+    /** A count shown on the item (99+ above 99). 0/undefined shows nothing. */
+    badge?: number;
+}
+interface NavGroup<Icon = unknown> {
+    label: string;
+    items: NavItem<Icon>[];
+}
+/**
+ * Is this item the current page? Exact match for "/", otherwise the path is the
+ * item or below it ("/board/123" is on "/board", "/boardroom" is not).
+ */
+declare function isActivePath(href: string, currentPath: string): boolean;
+/** "99+" above 99, nothing for 0 or less. */
+declare function badgeLabel(n: number | undefined): string | null;
+/** Read a boolean flag from localStorage; storage errors read as `fallback`. */
+declare function readFlag(key: string, fallback: boolean): boolean;
+declare function writeFlag(key: string, value: boolean): void;
+declare function readSet(key: string): Set<string>;
+declare function writeSet(key: string, value: Set<string>): void;
+/**
+ * Two initials for the avatar fallback: first letter of the first and the last
+ * word, upper-cased. One word gives one letter; nothing gives "?".
+ *
+ * There is deliberately no Gravatar here (owner decision D-1dc849): the avatar
+ * is the Broberg ID `picture`, and without one, initials. Gravatar would send a
+ * hash of the user's email to a US service on every render.
+ */
+declare function initials(name: string | undefined, email?: string): string;
+
+/** Where the bell gets its data. Swap it to point at any backend. */
+interface NotificationSource {
+    /** The rows to show (newest first). */
+    loadRows(): Promise<NotificationRow[]>;
+    /** THE count — your server's, which may exclude muted kinds (F074's counting rule). */
+    countUnseen(): Promise<number>;
+    /** Returns the ids that actually transitioned to seen. */
+    markSeen(ids: readonly string[]): Promise<string[]>;
+    markAllSeen(): Promise<string[]>;
+    /** Called with a callback that re-counts; return an unsubscribe. Optional. */
+    subscribe?(onChange: () => void): () => void;
+}
+/**
+ * The default source: a URL on your own backend, shaped after
+ * @broberg/notifications' server core so `createNotifications` sits right
+ * behind it.
+ *
+ *   GET  {url}           → { items: NotificationRow[], unseen: number }
+ *   POST {url}/seen      { ids: string[] } → { clearedIds: string[], count: number }
+ *   POST {url}/seen-all  → { clearedIds: string[], count: number }
+ *
+ * It re-counts when the window regains focus or the tab becomes visible, and on
+ * a timer (default 60 s). A failed GET THROWS — the bell shows «could not
+ * load», never an empty list: "could not fetch" and "nothing new" must not look
+ * the same.
+ */
+declare function createFetchNotificationSource(opts: {
+    url: string;
+    fetch?: typeof fetch;
+    /** Re-count interval in ms. 0 turns it off. Default 60 000. */
+    pollMs?: number;
+    credentials?: RequestCredentials;
+}): NotificationSource;
+/** An in-memory source for demos and tests. */
+declare function createMemoryNotificationSource(initial?: NotificationRow[]): NotificationSource & {
+    push(n: NotificationRow): void;
+    rows(): NotificationRow[];
+};
+/** "nu", "5 min", "3 t", "i går", "4 d" (da) or the English equivalents. */
+declare function relativeTime(ts: string | number, lang: "da" | "en", now?: number): string;
+declare const TEXT: {
+    readonly da: {
+        readonly openMenu: "Åbn menu";
+        readonly collapse: "Skjul sidemenu";
+        readonly expand: "Vis sidemenu";
+        readonly notifications: "Notifikationer";
+        readonly markAllRead: "Markér alle læst";
+        readonly noNotifications: "Ingen notifikationer endnu.";
+        readonly couldNotLoad: "Kunne ikke hente notifikationer.";
+        readonly seeAll: "Vis alle";
+        readonly close: "Luk";
+        readonly account: "Konto";
+        readonly signOut: "Log ud";
+        readonly theme: "Tema";
+        readonly light: "Lys";
+        readonly dark: "Mørk";
+        readonly system: "System";
+        readonly palette: "Palet";
+        readonly surfaces: "Flader";
+        readonly flat: "Flade";
+        readonly layered: "Lag";
+        readonly backdrop: "Baggrund";
+        readonly neurons: "Neuroner";
+        readonly plain: "Ren";
+    };
+    readonly en: {
+        readonly openMenu: "Open menu";
+        readonly collapse: "Hide sidebar";
+        readonly expand: "Show sidebar";
+        readonly notifications: "Notifications";
+        readonly markAllRead: "Mark all read";
+        readonly noNotifications: "No notifications yet.";
+        readonly couldNotLoad: "Could not load notifications.";
+        readonly seeAll: "See all";
+        readonly close: "Close";
+        readonly account: "Account";
+        readonly signOut: "Sign out";
+        readonly theme: "Theme";
+        readonly light: "Light";
+        readonly dark: "Dark";
+        readonly system: "System";
+        readonly palette: "Palette";
+        readonly surfaces: "Surfaces";
+        readonly flat: "Flat";
+        readonly layered: "Layered";
+        readonly backdrop: "Backdrop";
+        readonly neurons: "Neurons";
+        readonly plain: "Plain";
+    };
+};
+type Lang = keyof typeof TEXT;
+
+/** @jsxImportSource preact */
+
+type Icon = ComponentChildren;
+type PreactNavItem = NavItem<Icon>;
+type PreactNavGroup = NavGroup<Icon>;
+/** Called instead of a full page load when given. Return false to let the browser navigate. */
+type Navigate = (href: string) => void;
+/** True below 768px. Follows the window as it resizes. */
+declare function useIsMobile(): boolean;
+interface SidebarProps {
+    groups: PreactNavGroup[];
+    footer?: PreactNavItem[];
+    currentPath: string;
+    onNavigate?: Navigate;
+    /** Desktop: collapsed to nothing (drawer mode) or to the icon rail (rail mode). */
+    collapsed?: boolean;
+    onToggleCollapse?: () => void;
+    /** Phone, drawer mode: is the drawer open. */
+    mobileOpen?: boolean;
+    onClose?: () => void;
+    mobile?: "drawer" | "rail";
+    /** Shown at the top of the sidebar (e.g. the brand on a phone). */
+    header?: ComponentChildren;
+    /** localStorage key for which groups are folded. */
+    groupsKey?: string;
+    lang: Lang;
+}
+declare function Sidebar(p: SidebarProps): JSX.Element;
+interface NotificationBellProps {
+    /** Where the data comes from. Absent: the bell is still there, with an empty list. */
+    source?: NotificationSource;
+    onNavigate?: Navigate;
+    /** Required on purpose: a default would make "nobody chose" look like a choice. */
+    lang: Lang;
+}
+declare function NotificationBell({ source, onNavigate, lang }: NotificationBellProps): JSX.Element;
+interface ShellUser {
+    name?: string;
+    email?: string;
+    /** Broberg ID OIDC `picture`. Without it: initials. Never Gravatar (D-1dc849). */
+    picture?: string;
+}
+interface UserMenuItem {
+    id: string;
+    label: string;
+    icon?: Icon;
+    href?: string;
+    onSelect?: () => void;
+}
+interface UserMenuProps {
+    user: ShellUser;
+    /** «Konto» → Broberg ID's account page. */
+    accountHref?: string;
+    items?: UserMenuItem[];
+    onSignOut?: () => void | Promise<void>;
+    onNavigate?: Navigate;
+    /** Show Theme · Palette · Surfaces · Backdrop. Default true. */
+    appearance?: boolean;
+    lang: Lang;
+}
+declare function Avatar({ user, size }: {
+    user: ShellUser;
+    size?: number;
+}): JSX.Element;
+declare function UserMenu(p: UserMenuProps): JSX.Element;
+interface TopBarProps {
+    brand?: ComponentChildren;
+    /** Anything app-specific (project switcher, search) between brand and bell. */
+    actions?: ComponentChildren;
+    /** Drawer mode on a phone: show the hamburger and call this. */
+    onOpenMenu?: () => void;
+    notifications?: NotificationSource;
+    user?: ShellUser;
+    userMenu?: Omit<UserMenuProps, "user" | "lang" | "onNavigate">;
+    onNavigate?: Navigate;
+    lang: Lang;
+}
+/** Brand left, actions, then the notification bell and the user menu ALWAYS last, in that order. */
+declare function TopBar(p: TopBarProps): JSX.Element;
+declare function PageHeader(p: {
+    eyebrow?: ComponentChildren;
+    title: ComponentChildren;
+    description?: ComponentChildren;
+    actions?: ComponentChildren;
+}): JSX.Element;
+interface PageTab {
+    id: string;
+    label: ComponentChildren;
+    /** Path mode: the tab's own route. Query mode: ignored (?tab=id is used). */
+    href?: string;
+}
+/**
+ * Tabs as routes. `mode: "query"` puts the tab in `?tab=<id>` on the current
+ * path (first tab when absent); `mode: "path"` gives each tab its own href.
+ */
+declare function PageTabs(p: {
+    tabs: PageTab[];
+    currentUrl: string;
+    mode?: "query" | "path";
+    onNavigate?: Navigate;
+}): JSX.Element;
+interface AppShellProps {
+    brand?: ComponentChildren;
+    actions?: ComponentChildren;
+    groups: PreactNavGroup[];
+    footer?: PreactNavItem[];
+    currentPath: string;
+    onNavigate?: Navigate;
+    /** The notification centre's source. The bell is shown either way. */
+    notifications?: NotificationSource;
+    user?: ShellUser;
+    userMenu?: Omit<UserMenuProps, "user" | "lang" | "onNavigate">;
+    /** Phone behaviour: a slide-in drawer behind a hamburger, or a 60px icon rail. */
+    mobile?: "drawer" | "rail";
+    /** localStorage key prefix for the collapsed sidebar and folded groups. */
+    storageKey?: string;
+    /** Required: the shell ships no default language (see @broberg/notifications/shell). */
+    lang: Lang;
+    children?: ComponentChildren;
+}
+declare function AppShell(p: AppShellProps): JSX.Element;
+
+export { AppShell, type AppShellProps, Avatar, type Lang, type NavGroup, type NavItem, type Navigate, NotificationBell, type NotificationBellProps, type NotificationSource, PageHeader, type PageTab, PageTabs, type PreactNavGroup, type PreactNavItem, type ShellUser, Sidebar, type SidebarProps, TEXT, TopBar, type TopBarProps, UserMenu, type UserMenuItem, type UserMenuProps, badgeLabel, createFetchNotificationSource, createMemoryNotificationSource, initials, isActivePath, readFlag, readSet, relativeTime, useIsMobile, writeFlag, writeSet };