@knkcs/anker 1.8.0 → 1.9.0

package/dist/feedback/index.js

@@ -1,6 +1,6 @@
 import { Progress } from '../chunk-WEP2AIQ5.js';
-import { Spinner } from '../chunk-5YDCDC4B.js';
 import { IconButton } from '../chunk-JS7ZEZV3.js';
+import { Spinner } from '../chunk-5YDCDC4B.js';
 import { Box, Flex, Text, Stack, HStack } from '../chunk-G4QMIXLC.js';
 import { Dialog, Portal, ButtonGroup, Button } from '@chakra-ui/react';
 import { createContext, useState, useRef, useCallback, useContext, useEffect } from 'react';

package/dist/page-header-D-kxNn-f.d.ts

@@ -0,0 +1,51 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default from 'react';
+
+interface AuthCardProps {
+    /** Logo or wordmark, far-left of the topbar. */
+    logo?: React__default.ReactNode;
+    /** Right-side topbar content (help link, locale switcher, etc.). */
+    topBarRight?: React__default.ReactNode;
+    /** Hide the topbar entirely (rare — e.g. embedded preview). */
+    hideTopBar?: boolean;
+    /** Hide the dot-grid background (rare — e.g. printable). */
+    hideBackground?: boolean;
+    /** Small uppercase eyebrow above the title. */
+    eyebrow?: React__default.ReactNode;
+    /**
+     * Card title. Accepts a string or inline element — the component wraps
+     * it in an `<h3>` (semantic heading, 24px, semibold, default color).
+     * Avoid passing block elements (e.g. `<div>`) or pre-built headings.
+     */
+    title?: React__default.ReactNode;
+    /** Subtitle below title (14px, muted color, centered). */
+    subtitle?: React__default.ReactNode;
+    /** Card width preset. md = 440px (default), lg = 480px. */
+    size?: "md" | "lg";
+    /** Card footer slot. Bottom-bordered inside the card. */
+    footer?: React__default.ReactNode;
+    /** Page content inside the card body. */
+    children: React__default.ReactNode;
+}
+declare const AuthCard: {
+    ({ logo, topBarRight, hideTopBar, hideBackground, eyebrow, title, subtitle, size, footer, children, }: AuthCardProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+interface PageHeaderBreadcrumb {
+    label: string;
+    to?: string;
+}
+interface PageHeaderProps {
+    breadcrumbs?: PageHeaderBreadcrumb[];
+    title: React__default.ReactNode;
+    subtitle?: React__default.ReactNode;
+    actions?: React__default.ReactNode;
+    eyebrow?: React__default.ReactNode;
+}
+declare const PageHeader: {
+    ({ breadcrumbs, title, subtitle, actions, eyebrow, }: PageHeaderProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+export { AuthCard as A, PageHeader as P, type AuthCardProps as a, type PageHeaderBreadcrumb as b, type PageHeaderProps as c };

package/dist/templates/index.d.ts

@@ -0,0 +1,296 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { a as AuthCardProps, c as PageHeaderProps } from '../page-header-D-kxNn-f.js';
+
+/**
+ * Register page-action content (typically buttons rendered to the right of
+ * the page title) from any descendant of `<AppShell>`. The content is
+ * surfaced by the active page template inside its `<PageHeader>` actions
+ * slot.
+ *
+ * Pass `null` (or omit) to clear the registration. The hook is a no-op when
+ * called outside an AppShell, which keeps it safe to use in stories and
+ * isolated component tests.
+ */
+declare function usePageActions(content: ReactNode): void;
+/**
+ * Register context-rail content from any descendant of `<AppShell>`. The
+ * content is rendered in the rail column (assuming the AppShell has a rail
+ * slot enabled).
+ *
+ * Pass `null` (or omit) to clear the registration. The hook is a no-op when
+ * called outside an AppShell.
+ */
+declare function usePageRail(content: ReactNode): void;
+interface AppShellProps {
+    /**
+     * Sidebar element — the navigation column. Required. Typically an instance
+     * of `<Sidebar>` from `@knkcs/anker/components`. AppShell does not own the
+     * sidebar's collapsed-state — pass it through the Sidebar's own props.
+     */
+    sidebar: ReactNode;
+    /**
+     * Context rail element. Pass an instance of `<ContextRail>` to enable the
+     * rail column. Pass `null` (or omit) to disable the column entirely (no
+     * grid track is reserved). Pages can still register rail content via
+     * `usePageRail` — when the rail column is disabled, registered content is
+     * dropped silently.
+     *
+     * Tip: pass an _empty_ `<ContextRail>` if you want the column to exist
+     * (so child pages can populate it via `usePageRail`) without rendering
+     * any default content.
+     */
+    rail?: ReactNode;
+    /** Page content. */
+    children: ReactNode;
+}
+/**
+ * AppShell is the top-level layout for authenticated knkCMS pages. It owns
+ * the slot context that powers `usePageActions` and `usePageRail`, and
+ * arranges sidebar / main / rail in a 3-column CSS grid.
+ *
+ * AppShell is layout-only — it does not render a PageHeader, and it does not
+ * inject any business chrome. Pages compose `<IndexPageTemplate>`,
+ * `<DetailPageTemplate>`, etc. inside `children`.
+ */
+declare function AppShell({ sidebar, rail, children }: AppShellProps): react_jsx_runtime.JSX.Element;
+declare namespace AppShell {
+    var displayName: string;
+}
+
+interface AuthPageTemplateProps extends AuthCardProps {
+    /**
+     * Page body — typically a form or a verification CTA. Inherits all
+     * AuthCard slots (logo, topBarRight, eyebrow, title, subtitle, footer).
+     */
+    children: ReactNode;
+}
+/**
+ * Auth-flow page layout. Use for any pre-authentication screen (login,
+ * register, MFA, forgot-password, reset-password) and for short
+ * confirmation flows (email-verify, account-deleted). For consent
+ * dialogs, prefer `<OAuthConsentPageTemplate>` (denser layout).
+ *
+ * The template supplies a centered card with a dot-grid background, an
+ * optional topbar with logo + locale switcher, and a footer slot. To hide
+ * the topbar (rare — embedded preview, printable receipts) pass
+ * `hideTopBar`. To hide the dot-grid (printable) pass `hideBackground`.
+ */
+declare function AuthPageTemplate(props: AuthPageTemplateProps): react_jsx_runtime.JSX.Element;
+declare namespace AuthPageTemplate {
+    var displayName: string;
+}
+
+interface DashboardPageTemplateProps extends Pick<PageHeaderProps, "breadcrumbs" | "title" | "subtitle" | "eyebrow"> {
+    actions?: ReactNode;
+    /**
+     * Dashboard widgets. Children are placed inside a 12-column responsive
+     * CSS grid with `gap="4"`. Each child should set `gridColumn` (e.g.
+     * `"span 3"` for a quarter-width tile, `"span 6"` for half, `"span 12"`
+     * for full-width). The default per-child column span is `"span 12"`.
+     */
+    children: ReactNode;
+    /**
+     * Override the grid `gap` between widgets. @default "4" (= 16px)
+     */
+    gap?: string;
+}
+declare function DashboardPageTemplate({ breadcrumbs, title, subtitle, eyebrow, actions, children, gap, }: DashboardPageTemplateProps): react_jsx_runtime.JSX.Element;
+declare namespace DashboardPageTemplate {
+    var displayName: string;
+}
+
+interface DetailPageTemplateProps extends Pick<PageHeaderProps, "breadcrumbs" | "title" | "subtitle" | "eyebrow"> {
+    actions?: ReactNode;
+    /**
+     * Tab strip rendered immediately under the PageHeader. Typically a
+     * `<Tabs.Root>` containing a `<Tabs.List>` and one `<Tabs.Content>` per
+     * pane. The template does not render `<Tabs.Content>` separately —
+     * consumers control the tab body composition entirely.
+     */
+    tabs?: ReactNode;
+    /**
+     * Page body — the entity's identity card, tab bodies, edit forms, etc.
+     * Rendered with horizontal padding (`px="8"`) and top padding (`pt="6"`)
+     * so cards inside don't sit flush against the page edges. Override by
+     * passing a `<Box px="0" pt="0">…</Box>` if you need a flush layout.
+     */
+    children: ReactNode;
+    /**
+     * When `true`, removes the default `px="8" pt="6"` padding around
+     * `children`. Use for detail pages whose body is itself a full-bleed
+     * surface (e.g. a code editor). @default false
+     */
+    flush?: boolean;
+}
+declare function DetailPageTemplate({ breadcrumbs, title, subtitle, eyebrow, actions, tabs, children, flush, }: DetailPageTemplateProps): react_jsx_runtime.JSX.Element;
+declare namespace DetailPageTemplate {
+    var displayName: string;
+}
+
+interface ErrorPageProps {
+    /**
+     * Status code (404, 500, 403, …) shown as the page's largest piece of
+     * type. Pass any string — non-numeric codes like "OOPS" work too.
+     */
+    statusCode: ReactNode;
+    /** Short headline — e.g. "Page not found" or "Something went wrong". */
+    title: ReactNode;
+    /**
+     * One-paragraph explanation. Keep it short — the user is already in a
+     * frustrated state.
+     */
+    description?: ReactNode;
+    /**
+     * Action(s) — typically one solid button (back home / retry) plus an
+     * optional secondary link.
+     */
+    actions?: ReactNode;
+    /**
+     * Optional illustration rendered above the status code. Use sparingly.
+     */
+    illustration?: ReactNode;
+    /**
+     * Logo or wordmark rendered top-left. Useful for branded error pages
+     * served from the root domain.
+     */
+    logo?: ReactNode;
+}
+declare function ErrorPage({ statusCode, title, description, actions, illustration, logo, }: ErrorPageProps): react_jsx_runtime.JSX.Element;
+declare namespace ErrorPage {
+    var displayName: string;
+}
+
+interface IndexPageTemplateProps extends Pick<PageHeaderProps, "breadcrumbs" | "title" | "subtitle" | "eyebrow"> {
+    /**
+     * Optional explicit page-action content (rendered inside the PageHeader's
+     * actions slot). When omitted, the template falls back to whatever a
+     * descendant has registered via `usePageActions`.
+     */
+    actions?: ReactNode;
+    /**
+     * Optional tab strip rendered between the PageHeader and the toolbar.
+     * Pass an instance of `<Tabs.Root>` (with its own `<Tabs.List>` and
+     * `<Tabs.Content>`s). When omitted, no tab strip is rendered.
+     */
+    tabs?: ReactNode;
+    /**
+     * Toolbar element rendered between the tabs (if any) and the page body.
+     * Typically an instance of `<Toolbar>` from `@knkcs/anker/components`.
+     * Pass `null` to omit the toolbar entirely (rare).
+     */
+    toolbar?: ReactNode;
+    /**
+     * Page body — DataTable, list, empty state, or error/loading content.
+     * Rendered flush against the canvas. Add internal padding inside
+     * `children` if you need it.
+     */
+    children: ReactNode;
+}
+/**
+ * Canonical list-page layout. Renders PageHeader → optional Tabs → optional
+ * Toolbar → children, full-bleed against the canvas.
+ *
+ * Page actions are sourced from (in priority order): `actions` prop →
+ * registered slot via `usePageActions`. This lets a tab-pane component deep
+ * inside `children` register its own actions without prop-drilling.
+ */
+declare function IndexPageTemplate({ breadcrumbs, title, subtitle, eyebrow, actions, tabs, toolbar, children, }: IndexPageTemplateProps): react_jsx_runtime.JSX.Element;
+declare namespace IndexPageTemplate {
+    var displayName: string;
+}
+
+interface LoadingPageProps {
+    /** Optional logo rendered above the spinner. */
+    logo?: ReactNode;
+    /**
+     * Optional message rendered below the spinner. Keep it short
+     * (e.g. "Loading your workspace…").
+     */
+    message?: ReactNode;
+}
+declare function LoadingPage({ logo, message }: LoadingPageProps): react_jsx_runtime.JSX.Element;
+declare namespace LoadingPage {
+    var displayName: string;
+}
+
+interface MaintenancePageProps {
+    /** Logo rendered top-left. */
+    logo?: ReactNode;
+    /** Headline — e.g. "We'll be right back". */
+    title?: ReactNode;
+    /**
+     * One-paragraph message explaining what's happening and what users
+     * should do (typically "wait, we'll be back shortly").
+     */
+    description?: ReactNode;
+    /**
+     * Estimated-time-of-restoration banner. Pass a string like
+     * "Estimated back online: 14:30 UTC". Rendered below the description.
+     */
+    eta?: ReactNode;
+    /**
+     * Optional link to a status page or twitter status. Pass a fully-
+     * styled `<Link>` or an `<a>` element.
+     */
+    statusLink?: ReactNode;
+}
+declare function MaintenancePage({ logo, title, description, eta, statusLink, }: MaintenancePageProps): react_jsx_runtime.JSX.Element;
+declare namespace MaintenancePage {
+    var displayName: string;
+}
+
+interface MarketingPageTemplateProps {
+    /** Logo or wordmark, far-left of the topbar. */
+    logo?: ReactNode;
+    /** Navigation links and/or sign-in CTA, far-right of the topbar. */
+    topBarRight?: ReactNode;
+    /** Hide the topbar (rare). */
+    hideTopBar?: boolean;
+    /** Eyebrow above the hero title (uppercase, muted). */
+    heroEyebrow?: ReactNode;
+    /** Hero title — large display text. */
+    heroTitle?: ReactNode;
+    /** Hero subtitle — one-paragraph value statement. */
+    heroSubtitle?: ReactNode;
+    /** Hero CTAs — typically one solid button + one ghost link. */
+    heroActions?: ReactNode;
+    /** Optional visual rendered to the right of the hero copy on wide viewports. */
+    heroVisual?: ReactNode;
+    /**
+     * Feature sections, testimonials, etc. Rendered with `maxW="6xl"` and
+     * `marginInline="auto"` so content tracks a consistent reading column.
+     */
+    children?: ReactNode;
+    /** Footer content — copyright, secondary nav, contact. */
+    footer?: ReactNode;
+}
+declare function MarketingPageTemplate({ logo, topBarRight, hideTopBar, heroEyebrow, heroTitle, heroSubtitle, heroActions, heroVisual, children, footer, }: MarketingPageTemplateProps): react_jsx_runtime.JSX.Element;
+declare namespace MarketingPageTemplate {
+    var displayName: string;
+}
+
+interface SettingsPageTemplateProps extends Pick<PageHeaderProps, "breadcrumbs" | "title" | "subtitle" | "eyebrow"> {
+    actions?: ReactNode;
+    /**
+     * Tab strip. Settings pages should always have at least two tabs — if
+     * you only have one section, use DetailPageTemplate instead.
+     */
+    tabs: ReactNode;
+    /** Page body — typically Card-wrapped forms or DataLists. */
+    children: ReactNode;
+    /**
+     * Constrain the body width for readability. Settings forms read better
+     * at ~720px even on wide viewports. Pass a Chakra width token (`"3xl"`,
+     * `"4xl"`) or any CSS length. @default "3xl" (= 768px)
+     *
+     * Pass `"full"` to disable the constraint entirely.
+     */
+    maxBodyWidth?: string;
+}
+declare function SettingsPageTemplate({ breadcrumbs, title, subtitle, eyebrow, actions, tabs, children, maxBodyWidth, }: SettingsPageTemplateProps): react_jsx_runtime.JSX.Element;
+declare namespace SettingsPageTemplate {
+    var displayName: string;
+}
+
+export { AppShell, type AppShellProps, AuthPageTemplate, type AuthPageTemplateProps, DashboardPageTemplate, type DashboardPageTemplateProps, DetailPageTemplate, type DetailPageTemplateProps, ErrorPage, type ErrorPageProps, IndexPageTemplate, type IndexPageTemplateProps, LoadingPage, type LoadingPageProps, MaintenancePage, type MaintenancePageProps, MarketingPageTemplate, type MarketingPageTemplateProps, SettingsPageTemplate, type SettingsPageTemplateProps, usePageActions, usePageRail };