@cboxdk/cbox-ui 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentProps, ComponentType } from 'react';
 import { LucideIcon } from 'lucide-react';
 import { ClassValue } from 'clsx';
+export { T as TimePoint, n as niceTicks, t as timeTicks } from './scale-BaaY5qJs.js';
 
 /**
  * Identity contract every Cbox-family app must populate.
@@ -22,7 +23,8 @@ import { ClassValue } from 'clsx';
  */
 type CboxAppKey = string;
 type CboxUser = {
-    id: number;
+    /** Cbox ID's user id: numeric in id itself, a prefixed string (`usr_…`) in the apps that mirror it. */
+    id: number | string;
     name: string;
     email: string;
     avatar_url?: string | null;
@@ -32,7 +34,8 @@ type CboxUser = {
     timezone?: string | null;
 };
 type CboxOrganization = {
-    id: number;
+    /** Cbox ID's organization id: numeric in id itself, a prefixed string (`org_…`) in the apps that mirror it. */
+    id: number | string;
     slug: string;
     name: string;
     /**
@@ -59,8 +62,10 @@ type CboxAppLink = {
      * Defaults to the first letter of `name`.
      */
     monogram?: string;
-    /** Optional inline SVG path or URL for the launcher tile icon. */
-    iconUrl?: string;
+    /** Cbox ID's catalog `icon_url`: the app's icon for light surfaces (`https:` only). */
+    iconUrl?: string | null;
+    /** Cbox ID's catalog `icon_dark_url`: the app's icon for dark surfaces. */
+    iconDarkUrl?: string | null;
     /**
      * Accent colour for the monogram tile (and current-app highlight).
      * Hex string or any CSS colour the browser accepts. Falls back to
@@ -255,6 +260,8 @@ type LinkComponent = ComponentType<{
     className?: string;
     title?: string;
     'aria-label'?: string;
+    /** Set on the link of the page the person is on. */
+    'aria-current'?: 'page';
 }>;
 type CboxAppSidebarProps = {
     /** App key for the brand submark (and aria labels). */
@@ -389,7 +396,9 @@ type CboxBrandProps = {
      *  `light` on dark / coloured surfaces. */
     tone?: 'dark' | 'light';
     /** Collapsed mode renders only the square icon — used in the
-     *  collapsed-sidebar state. */
+     *  collapsed-sidebar state. The icon is the app's own icon from
+     *  Cbox ID's catalog (light and dark) once this browser has seen
+     *  the catalog, and the Cbox icon until then. */
     collapsed?: boolean;
     className?: string;
 };
@@ -494,6 +503,119 @@ type AppLauncherProps = {
  */
 declare function AppLauncher({ className, onLockedAppClick }: AppLauncherProps): react_jsx_runtime.JSX.Element | null;
 
+/** One app as the host's catalog endpoint lists it. */
+type CboxCatalogApp = {
+    key: string;
+    name: string;
+    launch_url: string;
+    /** Cbox ID's uploaded icon for light surfaces. */
+    icon_url?: string | null;
+    /** Cbox ID's uploaded icon for dark surfaces. */
+    icon_dark_url?: string | null;
+    description?: string | null;
+};
+type CboxAppCatalogState = {
+    status: 'idle' | 'loading';
+} | {
+    status: 'ready';
+    apps: CboxCatalogApp[];
+    refreshAfter: number;
+} | {
+    status: 'authorization_required';
+    authorizeUrl: string | null;
+} | {
+    status: 'unavailable';
+};
+type CboxAppCatalogProps = {
+    /**
+     * Same-origin URL the host serves the person's app catalog from (a proxy of Cbox ID's
+     * catalog, authorized for the signed-in person). `null` renders the control disabled, so the
+     * chrome keeps its shape on pages without an organization.
+     */
+    endpoint: string | null;
+    /** The app key of this app; its tile is marked current and does not navigate. */
+    currentAppKey: string;
+    className?: string;
+};
+/**
+ * Interpret the catalog endpoint's answer. The contract every Cbox app serves:
+ *
+ * - `200 { apps: [{ key, name, launch_url, icon_url?, icon_dark_url?, description? }], refresh_after?: seconds }`
+ * - `401`/`403 { authorize_url?: string }` or `{ state: 'authorization_required' }`: the
+ *   person has to (re)connect their catalog grant; `authorize_url` is where.
+ * - anything else: unavailable right now.
+ *
+ * Only `http(s)` launch URLs are kept: the tiles are links the person will click.
+ */
+declare function parseAppCatalog(ok: boolean, body: unknown): CboxAppCatalogState;
+/** The authorize link with `return_to` set to where the person is, when it is on this origin. */
+declare function authorizeHref(authorizeUrl: string | null, location: {
+    origin: string;
+    pathname: string;
+    search: string;
+}): string | null;
+/**
+ * The Switch-app control: a grid of the Cbox apps this person can open, read live from the
+ * host's catalog endpoint. The host owns the endpoint and the grant; this renders the answer,
+ * refreshes it when it expires while the panel is open, and offers the way back to Cbox ID
+ * when the grant is missing. Each tile shows the app's icon from the catalog (light and dark),
+ * and the answer is kept so `CboxServiceMark` paints the app's own mark from it.
+ */
+declare function CboxAppCatalog({ endpoint, currentAppKey, className }: CboxAppCatalogProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Every Cbox app's icon comes from Cbox ID's catalog: one light and one dark upload per app
+ * (`icon_url`, `icon_dark_url`). There is no local copy of the marks in this package or in an
+ * app. The last catalog the browser saw is kept here so an app's own mark and the switcher
+ * paint at once on the next page; the live answer replaces it when it arrives.
+ */
+type CboxKnownApp = {
+    key: string;
+    name: string;
+    icon_url: string | null;
+    icon_dark_url: string | null;
+};
+/** Keep the catalog the person just loaded, so every mark on this origin repaints from it. */
+declare function rememberAppCatalog(apps: ReadonlyArray<{
+    key: string;
+    name: string;
+    icon_url?: string | null;
+    icon_dark_url?: string | null;
+}>): void;
+/** The last catalog this browser kept; empty on the server and before the first answer. */
+declare function useKnownAppCatalog(): CboxKnownApp[];
+/** Only `https:` icon URLs are rendered: the icons are hosted by Cbox ID. */
+declare function secureIconUrl(url: unknown): string | null;
+type CboxAppIconProps = {
+    /** The app's name; its first two letters stand in when it has no icon. */
+    name: string;
+    /** Catalog `icon_url`: the icon for light surfaces (or the only one). */
+    iconUrl?: string | null;
+    /** Catalog `icon_dark_url`: the icon for dark surfaces. */
+    iconDarkUrl?: string | null;
+    /** Size and shape of the icon box, e.g. `h-6 w-6`. */
+    className?: string;
+    /** Rendered instead of initials when the app has no usable icon. */
+    fallback?: ReactNode;
+};
+/**
+ * One app's icon from the catalog. With both uploads it renders two images and the token
+ * stylesheet shows the one for the current theme (`.dark` or `[data-theme="dark"]` on the
+ * root, the same switch the tokens use). Without an icon, or when it fails to load, it shows
+ * the app's initials.
+ */
+declare function CboxAppIcon({ name, iconUrl, iconDarkUrl, className, fallback }: CboxAppIconProps): react_jsx_runtime.JSX.Element;
+type CboxServiceMarkProps = {
+    /** The app key in Cbox ID's catalog (`signals`, `infra`, …). */
+    appKey: string;
+    /** Size of the mark. Default `h-6 w-6`. */
+    className?: string;
+    /** Shown while the catalog has not told this browser the app's icon yet. Default nothing. */
+    fallback?: ReactNode;
+};
+/** An app's own mark (its rail or brand icon), read from the catalog this browser last kept. */
+declare function CboxServiceMark({ appKey, className, fallback }: CboxServiceMarkProps): react_jsx_runtime.JSX.Element;
+
 type AppSwitcherProps = {
     className?: string;
     /**
@@ -595,7 +717,14 @@ type Props$3 = {
      * is consistency across apps.
      */
     extras?: ReactNode;
+    placement?: 'bottom-end' | 'top-start';
     className?: string;
+    /**
+     * The router's link for the account and organization rows, when they are pages of this
+     * app (an Inertia `Link` keeps the visit client-side). Default: a plain anchor, which is
+     * right when the rows deep-link into Cbox ID on another origin.
+     */
+    LinkComponent?: LinkComponent;
 };
 /**
  * User-menu dropdown. Always exposes:
@@ -605,7 +734,7 @@ type Props$3 = {
  *
  * The arrows signal cross-app navigation — id is canonical.
  */
-declare function UserMenu({ extras, className }: Props$3): react_jsx_runtime.JSX.Element;
+declare function UserMenu({ extras, className, placement, LinkComponent: Link }: Props$3): react_jsx_runtime.JSX.Element;
 
 /**
  * Combobox — the canonical select replacement for the Cbox suite.
@@ -1380,4 +1509,75 @@ declare function parseUrlSearch<S extends UrlSchema>(search: string, schema: S):
  */
 declare function buildUrlSearch<S extends UrlSchema>(state: InferUrlState<S>, schema: S): string;
 
-export { AppContent, AppLauncher, AppShell, AppSwitcher, type CboxAppKey, type CboxAppLink, CboxAppShell, type CboxAppShellProps, CboxAppSidebar, type CboxAppSidebarProps, CboxBrand, type CboxBrandProps, type CboxIdContextValue, CboxIdProvider, CboxMobileNavDrawer, type CboxMobileNavDrawerProps, type CboxNavItem, type CboxNavSection, type CboxNotificationPreviewItem, type CboxNotificationsState, CboxOrgContextBar, type CboxOrgContextBarProps, type CboxOrganization, CboxSurfaces, type CboxSurfacesProps, type CboxUser, Combobox, type ComboboxAvatar, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type ContextAvatar, ContextAvatarChip, ContextBar, type ContextCrumb, type ContextItem, DataPanel, EmptyState, Heading, type InboxState, type InferUrlState, KeyValue, KeyValueList, type LinkComponent, NotificationsBell, OrgSwitcher, PageHeader, PageShell, type PageTabSpec, PageTabs, type PageTabsProps, type PageWidth, PanelBody, type RealtimeState, type RealtimeStatus, RowLink, type RowLinkProps, SearchTrigger, SectionHeader, StatTile, StatusPill, type SurfaceArgs, type SurfaceConfig, type SurfaceController, type SurfaceId, TopBar, type Transport, type UrlField, type UrlSchema, UserMenu, buildUrlSearch, cn, defineUrlSchema, parseUrlSearch, urlBoolean, urlEnum, urlNumber, urlString, urlStringArray, useCboxId, useCboxIdOptional, useCboxSurfaces, useCboxSurfacesOptional };
+type CboxTranslationValues = Record<string, string | number>;
+type CboxTranslator = (message: string, values?: CboxTranslationValues) => string;
+declare function interpolate(message: string, values?: CboxTranslationValues): string;
+/** Optional and additive: without a provider existing consumers retain English. */
+declare function CboxLocalizationProvider({ locale, translate, formatDate, children }: {
+    locale: string;
+    translate: CboxTranslator;
+    formatDate?: (value: string) => string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useCboxLocalization(): {
+    locale: string;
+    t: CboxTranslator;
+    formatDate: (value: string) => string;
+};
+
+type CboxNavArea = CboxNavItem & {
+    items?: CboxNavItem[];
+};
+type CboxWorkspaceShellProps = {
+    appKey: string;
+    brandSubmark: string;
+    areas: CboxNavArea[];
+    currentPath: string;
+    LinkComponent: LinkComponent;
+    context: ReactNode;
+    tools: ReactNode;
+    account: ReactNode;
+    children: ReactNode;
+    /** Where the brand row links. Default `/`. */
+    brandHref?: string;
+    /** `id` of the `<main>` landmark, so a host's skip link can target it. Default `main-content`. */
+    mainId?: string;
+    /**
+     * Rail pinned open. Pass `pinned` + `onPinnedChange` to control it (the host persists the
+     * preference, in a cookie or Cbox ID), or `defaultPinned` to seed the shell's own state.
+     */
+    pinned?: boolean;
+    defaultPinned?: boolean;
+    onPinnedChange?: (pinned: boolean) => void;
+    /** Contextual subnav collapsed to its strip. Controlled and uncontrolled as `pinned`. */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+};
+/**
+ * How well `href` matches `path`: the href's length when the path is the href or beneath it,
+ * -1 otherwise. `/` matches only itself, so a home item never claims every page.
+ */
+declare function navMatchLength(path: string, href: string): number;
+/** The item whose href is the most specific match for `path`, or undefined. */
+declare function activeNavItem<T extends CboxNavItem>(path: string, items: readonly T[]): T | undefined;
+/**
+ * The area `path` is in: the one holding the most specific match among its own href and its
+ * items' hrefs. A first-match would put every page beneath an area at `/` (an overview, a
+ * dashboard) under that area and never show another area's subnav.
+ */
+declare function activeNavArea<T extends CboxNavArea>(path: string, areas: readonly T[]): T | undefined;
+/** Two-tier workspace navigation. Route ownership and preference persistence stay with the host. */
+declare function CboxWorkspaceShell({ appKey, brandSubmark, areas, currentPath, LinkComponent: Link, context, tools, account, children, brandHref, mainId, pinned: pinnedProp, defaultPinned, onPinnedChange, collapsed: collapsedProp, defaultCollapsed, onCollapsedChange }: CboxWorkspaceShellProps): react_jsx_runtime.JSX.Element;
+
+/** The chart tokens in order, for series that set their own colour. */
+declare const CHART_PALETTE: string[];
+/** A row's shape over the window, small: a line with a faint area, zero at the bottom. Decorative. */
+declare function Sparkline({ values, color, width, height }: {
+    values: number[];
+    color?: string;
+    width?: number;
+    height?: number;
+}): react_jsx_runtime.JSX.Element | null;
+
+export { AppContent, AppLauncher, AppShell, AppSwitcher, CHART_PALETTE, CboxAppCatalog, type CboxAppCatalogProps, type CboxAppCatalogState, CboxAppIcon, type CboxAppIconProps, type CboxAppKey, type CboxAppLink, CboxAppShell, type CboxAppShellProps, CboxAppSidebar, type CboxAppSidebarProps, CboxBrand, type CboxBrandProps, type CboxCatalogApp, type CboxIdContextValue, CboxIdProvider, type CboxKnownApp, CboxLocalizationProvider, CboxMobileNavDrawer, type CboxMobileNavDrawerProps, type CboxNavArea, type CboxNavItem, type CboxNavSection, type CboxNotificationPreviewItem, type CboxNotificationsState, CboxOrgContextBar, type CboxOrgContextBarProps, type CboxOrganization, CboxServiceMark, type CboxServiceMarkProps, CboxSurfaces, type CboxSurfacesProps, type CboxTranslationValues, type CboxTranslator, type CboxUser, CboxWorkspaceShell, type CboxWorkspaceShellProps, Combobox, type ComboboxAvatar, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type ContextAvatar, ContextAvatarChip, ContextBar, type ContextCrumb, type ContextItem, DataPanel, EmptyState, Heading, type InboxState, type InferUrlState, KeyValue, KeyValueList, type LinkComponent, NotificationsBell, OrgSwitcher, PageHeader, PageShell, type PageTabSpec, PageTabs, type PageTabsProps, type PageWidth, PanelBody, type RealtimeState, type RealtimeStatus, RowLink, type RowLinkProps, SearchTrigger, SectionHeader, Sparkline, StatTile, StatusPill, type SurfaceArgs, type SurfaceConfig, type SurfaceController, type SurfaceId, TopBar, type Transport, type UrlField, type UrlSchema, UserMenu, activeNavArea, activeNavItem, authorizeHref, buildUrlSearch, cn, defineUrlSchema, interpolate, navMatchLength, parseAppCatalog, parseUrlSearch, rememberAppCatalog, secureIconUrl, urlBoolean, urlEnum, urlNumber, urlString, urlStringArray, useCboxId, useCboxIdOptional, useCboxLocalization, useCboxSurfaces, useCboxSurfacesOptional, useKnownAppCatalog };