prime-ui-kit 0.15.0 → 0.17.0

package/dist/layout/page/Page.d.ts

@@ -0,0 +1,263 @@
+import * as React from "react";
+export type PageLabels = {
+    /** Name of the menu button the top bar draws while the shell's Sidebar is off-canvas. */
+    menu: string;
+    /** Name of the «⋯» button the top bar's actions fold into when the row runs out of width. */
+    more: string;
+    /** Name of `Page.BackButton` (back from the detail to the list on a narrow split). */
+    back: string;
+};
+export declare const PAGE_LABELS: PageLabels;
+type DivProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
+};
+/** Cap of the page column. */
+export type PageMaxWidth = "full" | "readable" | "wide";
+export type PageRootProps = DivProps & {
+    /**
+     * Cap of everything but the top bar, centred: `full` — the whole main; `readable` — 42rem (`--prime-layout-reading-max-width`); `wide` — 75rem (`--prime-layout-content-max-width`).
+     */
+    maxWidth?: PageMaxWidth;
+    /**
+     * The page takes the height of main (`AppShell.Root fillViewport`) and the body takes what the bar and the header leave: for a full-height table, board, chat or `Page.Split`.
+     */
+    fill?: boolean;
+    /**
+     * Built-in strings of every part, see Labels.
+     */
+    labels?: Partial<PageLabels>;
+};
+/**
+ * The page: the column inside `AppShell.Main` that holds the top bar, the header and the body. In
+ * the shell it takes the shell's gutters and top air (`--page-gutter`, `--page-top` from main);
+ * outside it brings none. `maxWidth` caps and centres everything but the top bar, which runs the
+ * width of the panel.
+ */
+declare function PageRoot({ maxWidth, fill, labels: labelsProp, className, ...rest }: PageRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageRoot {
+    var displayName: string;
+}
+export type PageTopBarProps = React.HTMLAttributes<HTMLElement> & {
+    /**
+     * Sticks to the top of the page's scroller (`AppShell.Main`); `false` — scrolls away with the page. On a screen lower than 480px it scrolls anyway.
+     */
+    sticky?: boolean;
+    /**
+     * Once the flow `Page.Title` scrolls out under the bar, the bar repeats it as the last level of its heading (of its `Breadcrumb` path, which folds for it), unless the path ends at it; it leaves when the title returns.
+     */
+    collapse?: boolean;
+    ref?: React.Ref<HTMLElement>;
+};
+/**
+ * The page's strip at its top edge, across the panel. Up to four groups in one grid —
+ * `Page.Heading`, `Page.Tools`, `Page.Actions` on the first line, `Page.Chips` under them — laid
+ * out by one plan chosen from their natural widths (`planBar`): one line while everything fits;
+ * then the tools take a line of their own; then the buttons give way to their icons, secondary
+ * first, and fold into «⋯»; only then does a heading with a path stack (path over title), and a
+ * heading without one truncate. Sticky inside the scroller of
+ * the page; while the shell's Sidebar is off-canvas it starts with the menu button. With
+ * `collapse` it repeats the flow `Page.Title` once that title scrolls out under the bar.
+ */
+declare function PageTopBar({ sticky, collapse, className, children, ref, ...rest }: PageTopBarProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageTopBar {
+    var displayName: string;
+}
+export type PageHeaderProps = DivProps;
+/**
+ * The document header in the page flow (settings, long forms, overviews): a `Page.Heading` and
+ * its `Page.Actions` in one row; the actions wrap under the heading on a narrow column. In a
+ * `Page.TopBar` the same parts stand directly in the bar.
+ */
+declare function PageHeader({ className, children, ...rest }: PageHeaderProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageHeader {
+    var displayName: string;
+}
+export type PageHeadingProps = DivProps;
+/**
+ * The title group: an optional `Breadcrumb` path, `Page.Title`, `Page.Description`. In the bar
+ * the title is the path's last level — the path, a chevron and the title on one line, the
+ * description under the whole line, both truncating; in the flow the path stands over a large
+ * title and the description wraps.
+ */
+declare function PageHeading({ className, children, ...rest }: PageHeadingProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageHeading {
+    var displayName: string;
+}
+export type PageTitleProps = React.HTMLAttributes<HTMLHeadingElement> & {
+    ref?: React.Ref<HTMLHeadingElement>;
+};
+/**
+ * The page's `<h1>`: the last level of the path in the top bar (it truncates), a large title in
+ * the flow. A flow title is what a `collapse` top bar repeats once it scrolls away.
+ */
+declare function PageTitle({ className, children, ref, ...rest }: PageTitleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageTitle {
+    var displayName: string;
+}
+export type PageDescriptionProps = React.HTMLAttributes<HTMLParagraphElement> & {
+    ref?: React.Ref<HTMLParagraphElement>;
+};
+/** One line of context that carries data (a period, a count): truncates in the bar, wraps in the flow. */
+declare function PageDescription({ className, children, ...rest }: PageDescriptionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageDescription {
+    var displayName: string;
+}
+export type PageActionsProps = DivProps;
+/**
+ * The page's buttons: at the end of a `Page.Header` or a `Page.Section` heading in the flow (they
+ * wrap under it on a narrow column), on the first line of a `Page.TopBar` at every width. In the
+ * bar, when the line runs short, Buttons with an icon show only it — the secondary ones first,
+ * then the primary (the first solid Button) — with their label as name and tooltip; then the
+ * secondary Buttons fold into a «⋯» menu. Anything that is not a `Button.Root` stays as it is.
+ */
+declare function PageActions(props: PageActionsProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageActions {
+    var displayName: string;
+}
+export type PageToolsProps = DivProps;
+/**
+ * The page's tools — sections, search and filter, view — as kit controls in the order written.
+ * On the bar's first line each keeps its natural width; on a line of their own they fill it:
+ * a search (`SmartFilter.Toolbar`, `Input.Root`) takes the room first, switchers share the rest
+ * (a `SegmentedControl.Root` is `fullWidth` unless set), and they wrap when one line is not
+ * enough. Named (`aria-label`), it is a `group`.
+ */
+declare function PageTools({ className, children, ref, ...rest }: PageToolsProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageTools {
+    var displayName: string;
+}
+export type PageChipsProps = DivProps;
+/** Active filters (`SmartFilter.Chips`) on a line of their own under the bar; gone while empty. */
+declare function PageChips({ className, ...rest }: PageChipsProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageChips {
+    var displayName: string;
+}
+export type PageBodyProps = DivProps;
+/** The page content: blocks of one screen 24 apart, a `Page.Section` 40 from its neighbours. */
+declare function PageBody({ className, ...rest }: PageBodyProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageBody {
+    var displayName: string;
+}
+/** Where the heading of a section stands: over its content or in a column beside it. */
+export type PageSectionLayout = "stack" | "aside";
+export type PageSectionProps = Omit<React.HTMLAttributes<HTMLElement>, "title"> & {
+    /**
+     * The visible heading (`h2`); it also names the section.
+     */
+    label: React.ReactNode;
+    /**
+     * One line of context under the heading, in secondary body-s.
+     */
+    description?: React.ReactNode;
+    /**
+     * `stack` — the heading over the content; `aside` — a ~16rem heading column beside it (a settings page), above it once the content would get narrower than 30rem.
+     */
+    layout?: PageSectionLayout;
+    ref?: React.Ref<HTMLElement>;
+};
+/**
+ * A titled section of the page: an `h2` heading (with an optional description and `Page.Actions`
+ * at its end) over its content. Sections stand further apart than the plain blocks of the body,
+ * so the air shows where a new topic starts.
+ */
+declare function PageSection({ label, description, layout, className, children, ...rest }: PageSectionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageSection {
+    var displayName: string;
+}
+export type PageGridProps = DivProps;
+/**
+ * The grid of the page's tiles (KPI cards, charts, panels): 12 columns, one gap on both axes.
+ * Columns follow the grid's own width, so tiles fold on a narrow panel by themselves.
+ */
+declare function PageGrid({ className, ...rest }: PageGridProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageGrid {
+    var displayName: string;
+}
+/** Columns of 12 a cell spans on a wide grid. */
+export type PageCellSpan = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/** Rows a cell spans. */
+export type PageCellRows = 1 | 2 | 3 | 4;
+export type PageCellProps = DivProps & {
+    /**
+     * Columns of 12 on a wide grid (64rem+). Narrower grids round it: see Grid columns in COMPONENT.md.
+     */
+    span?: PageCellSpan;
+    /**
+     * Rows the cell spans from 40rem: a chart beside two stacked tiles (`ChartFrame.Plot height="fill"` fills the height).
+     */
+    rows?: PageCellRows;
+};
+/** One tile place in `Page.Grid`; its child (a Card, a ChartFrame) fills it. */
+declare function PageCell({ span, rows, className, ...rest }: PageCellProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageCell {
+    var displayName: string;
+}
+export type PageSplitProps = DivProps & {
+    /**
+     * The detail is open (a record is chosen), controlled. On a narrow split it takes the place of the list; on a wide one both panes stay.
+     */
+    open?: boolean;
+    /**
+     * Initial open state, uncontrolled.
+     */
+    defaultOpen?: boolean;
+    /**
+     * `Page.BackButton` closes the detail (`false`); clear the chosen record there.
+     */
+    onOpenChange?: (open: boolean) => void;
+};
+/**
+ * List + detail (mail, a messenger, a ticket queue): two panes side by side from 48rem of its own
+ * width, one at a time below it — the list, or the open detail with a back button. Takes the free
+ * height of a filling page; each pane gives its last child the free height.
+ */
+declare function PageSplit({ open: openProp, defaultOpen, onOpenChange, className, children, ...rest }: PageSplitProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageSplit {
+    var displayName: string;
+}
+export type PageListProps = DivProps;
+/**
+ * The list pane of the split: a fixed column on a wide split, the whole split while the detail is
+ * closed. It remembers the control that had focus, so going back returns there.
+ */
+declare function PageList(props: PageListProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageList {
+    var displayName: string;
+}
+export type PageDetailProps = DivProps;
+/** The detail pane of the split: the rest of a wide split; on a narrow one it replaces the list while open. */
+declare function PageDetail(props: PageDetailProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageDetail {
+    var displayName: string;
+}
+export type PageBackButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
+    ref?: React.Ref<HTMLButtonElement>;
+};
+/**
+ * Back from the detail to the list: a soft neutral icon Button named by `labels.back`, shown only
+ * while the split shows one pane. Put it at the start of the detail's header.
+ */
+declare function PageBackButton({ className, onClick, ...rest }: PageBackButtonProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageBackButton {
+    var displayName: string;
+}
+export declare const Page: {
+    Root: typeof PageRoot;
+    TopBar: typeof PageTopBar;
+    Header: typeof PageHeader;
+    Heading: typeof PageHeading;
+    Title: typeof PageTitle;
+    Description: typeof PageDescription;
+    Actions: typeof PageActions;
+    Tools: typeof PageTools;
+    Chips: typeof PageChips;
+    Body: typeof PageBody;
+    Section: typeof PageSection;
+    Grid: typeof PageGrid;
+    Cell: typeof PageCell;
+    Split: typeof PageSplit;
+    List: typeof PageList;
+    Detail: typeof PageDetail;
+    BackButton: typeof PageBackButton;
+};
+export {};