prime-ui-kit 0.9.0 → 0.9.2

package/dist/internal/slot.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 type AnyProps = Record<string, unknown>;
 export type SlotProps = {
     children?: React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
 } & AnyProps;
 /**
  * Merges its own props onto the single React child element.
@@ -10,10 +11,15 @@ export type SlotProps = {
  * Merge rules:
  * - `className` — space-joined (slot first, child second)
  * - `style`     — shallow-merged; child keys win
- * - `on*` handlers — both fire; child handler runs first
- * - All other props — child overrides slot
- * - `ref` — merged via `mergeRefs`
+ * - `aria-describedby` — both ids, child first
+ * - `on*` handlers — both fire, child first; a child `preventDefault()` skips the slot handler
+ * - All other props — a defined child prop overrides the slot prop
+ * - `ref` — merged with the child's ref
+ * - `aria-disabled` on the slot — clicks (pointer and keyboard-activated) are stopped in the capture
+ *   phase, so the child's own `onClick` never runs and a link does not navigate
  */
-export declare const Slot: React.ForwardRefExoticComponent<Omit<SlotProps, "ref"> & React.RefAttributes<HTMLElement>>;
+export declare function Slot({ children, ref, ...slotProps }: SlotProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Slot {
+    var displayName: string;
+}
 export {};
-//# sourceMappingURL=slot.d.ts.map

package/dist/internal/states.d.ts

@@ -5,13 +5,15 @@
 /** Control size tiers: xs 28 · s 32 · m 36 · l 40 · xl 48. Default is always `m`. */
 export declare const controlSizes: readonly ["xs", "s", "m", "l", "xl"];
 export type ControlSize = (typeof controlSizes)[number];
+/** The tier `n` steps smaller, never below `xs`: a control nested in another (foundation §6 pairing). */
+export declare function stepDown(size: ControlSize, n?: number): ControlSize;
 /** Visual treatment. */
 export declare const variants: readonly ["solid", "soft", "outline", "ghost"];
 export type Variant = (typeof variants)[number];
 /** Semantic color. Destructive is `danger`. */
 export declare const tones: readonly ["neutral", "accent", "success", "warning", "danger", "info"];
 export type Tone = (typeof tones)[number];
-/** Decorative palette color (Badge, Tag, Avatar). */
+/** Decorative palette color (Badge, Avatar). */
 export declare const paletteColors: readonly ["gray", "blue", "green", "orange", "red", "yellow", "purple", "sky", "pink", "teal"];
 export type PaletteColor = (typeof paletteColors)[number];
 /** Values of `data-state`. */
@@ -23,4 +25,3 @@ export type DataState = (typeof dataStates)[number];
  */
 export declare const textTones: readonly ["default", "secondary", "muted", "accent", "success", "warning", "danger"];
 export type TextTone = (typeof textTones)[number];
-//# sourceMappingURL=states.d.ts.map

package/dist/internal/swatch.d.ts

@@ -0,0 +1,56 @@
+import * as React from "react";
+export type ColorPreset = {
+    /** CSS color stored as the value (`onValueChange` returns it as is). */
+    value: string;
+    /** Human-readable name: the option's accessible name and the trigger's `aria-label` suffix. */
+    label: string;
+};
+/**
+ * Default quick colors: the kit palette primitives (`tokens/primitives.ts`).
+ * Row 1 — step 500 of eight hues, row 2 — step 700 of the same hues.
+ * Take `COLOR_PRESETS.slice(0, 8)` for a single row of eight.
+ */
+export declare const COLOR_PRESETS: readonly ColorPreset[];
+/** One selectable swatch: `null` is «no color». */
+export type SwatchOption = {
+    value: string | null;
+    label: string;
+    contrast: "light" | "dark";
+};
+/** The presets as swatch options, plus the «no color» option at the end when `allowEmpty`. */
+export declare function useSwatchOptions(presets: readonly ColorPreset[], allowEmpty: boolean, emptyLabel: string): SwatchOption[];
+/** Class of a selectable swatch (button or option) sized by `--swatch-size` / `--swatch-radius`. */
+export declare const swatchClass: string;
+/**
+ * Tier of a swatch grid, from `data-size` on the same element: `--swatch-radius`, `--swatch-gap`
+ * and `--swatch-size` = `--swatch-base` − 8. The host picks the base: `--swatch-base-control`
+ * (control height) or `--swatch-base-item` (menu item height).
+ */
+export declare const swatchTierClass: string;
+/** Color layer of a swatch; `null` draws the "no color" checkerboard. */
+export declare function SwatchFill({ value }: {
+    value: string | null;
+}): import("react/jsx-runtime").JSX.Element;
+/** Inside a selectable swatch: the color layer and, when selected, the contrasting check. */
+export declare function SwatchContent({ value, selected }: {
+    value: string | null;
+    selected: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export type SwatchChipProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+    value: string | null;
+    ref?: React.Ref<HTMLSpanElement>;
+};
+/**
+ * The current color as a small square for a trigger (e.g. inside `Button.Root`): sized from the
+ * host's `--prime-icon-size`, with the faint inner edge; `aria-hidden` — the trigger is named.
+ */
+export declare function SwatchChip({ value, className, ...rest }: SwatchChipProps): import("react/jsx-runtime").JSX.Element;
+/** Case- and space-insensitive color comparison; `null` means "no color". */
+export declare function sameColor(a: string | null, b: string | null): boolean;
+/**
+ * sRGB channels (0–255) of a hex, `rgb()` or `hsl()` color; `null` for anything else (named colors,
+ * other spaces). Kept dependency-free so the swatches stay out of the ColorPicker entry.
+ */
+export declare function colorToRgb(value: string): [number, number, number] | null;
+/** `dark` when a dark mark contrasts better with the color than a light one (WCAG luminance). */
+export declare function markContrast(value: string): "light" | "dark";

package/dist/internal/touchTarget.d.ts

@@ -0,0 +1,4 @@
+/** A 44px hit area on coarse pointers, both axes, the visual size unchanged (`touchTarget.module.css`). */
+export declare const touchTargetClass: string;
+/** The same hit area grown in height only: a segment beside other content of its host. */
+export declare const touchTargetBlockClass: string;

package/dist/layout/app-header/AppHeader.d.ts

@@ -0,0 +1,110 @@
+import * as React from "react";
+import { type DividerProps } from "@/components/divider/Divider";
+export type AppHeaderLabels = {
+    /** Name of the menu button that opens the off-canvas Sidebar. */
+    menu: string;
+};
+type HeaderProps = React.HTMLAttributes<HTMLElement> & {
+    ref?: React.Ref<HTMLElement>;
+};
+type DivProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
+};
+export type AppHeaderRootProps = HeaderProps & {
+    labels?: Partial<AppHeaderLabels>;
+};
+/**
+ * The bar at the very top of the content panel: where you are, global search, a few actions.
+ * One row as high as the Sidebar brand row, so the two read as one line; sticky; lays itself out
+ * from its own width (narrow: the search folds into an icon, the title truncates).
+ */
+declare function AppHeaderRoot({ labels, className, children, ...rest }: AppHeaderRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderRoot {
+    var displayName: string;
+}
+export type AppHeaderStartProps = DivProps;
+/** The leading zone: the menu button, a back button, the title or breadcrumbs. Takes the free width. */
+declare function AppHeaderStart({ className, ...rest }: AppHeaderStartProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderStart {
+    var displayName: string;
+}
+export type AppHeaderTitleProps = DivProps;
+/**
+ * Where you are: an optional `AppHeader.Icon`, the name and an optional `AppHeader.Description`
+ * under it — the same anatomy as the Sidebar brand. The name truncates.
+ */
+declare function AppHeaderTitle({ className, children, ...rest }: AppHeaderTitleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderTitle {
+    var displayName: string;
+}
+export type AppHeaderIconProps = React.HTMLAttributes<HTMLSpanElement> & {
+    ref?: React.Ref<HTMLSpanElement>;
+};
+/**
+ * Decorative glyph before the title on a tile shaped like the bar's soft buttons (control m).
+ * Not a Thumbnail: its tiers (32 · 40) miss the control height the buttons beside it have.
+ */
+declare function AppHeaderIcon({ className, ...rest }: AppHeaderIconProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderIcon {
+    var displayName: string;
+}
+export type AppHeaderDescriptionProps = React.HTMLAttributes<HTMLSpanElement> & {
+    ref?: React.Ref<HTMLSpanElement>;
+};
+/** Muted second line under the title (a workspace, a period); hidden on a narrow header. */
+declare function AppHeaderDescription({ className, ...rest }: AppHeaderDescriptionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderDescription {
+    var displayName: string;
+}
+export type AppHeaderSeparatorProps = Omit<DividerProps, "orientation" | "children">;
+/** A short vertical line between groups in a zone (a back button | the path), with air on both sides. */
+declare function AppHeaderSeparator({ className, ...rest }: AppHeaderSeparatorProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderSeparator {
+    var displayName: string;
+}
+export type AppHeaderSearchProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
+    /** Placeholder text; also the button's name when the header is narrow and the field folds. */
+    children: React.ReactNode;
+    /** Key hint at the end. Default `⌘K`; `null` hides it. */
+    shortcut?: React.ReactNode;
+    ref?: React.Ref<HTMLButtonElement>;
+};
+/**
+ * Global search entry: looks like a field, works as a button that opens your CommandMenu (wire
+ * `onClick` and the shortcut). On a narrow header it folds into a square search button.
+ */
+declare function AppHeaderSearch({ children, shortcut, className, ...rest }: AppHeaderSearchProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderSearch {
+    var displayName: string;
+}
+export type AppHeaderActionsProps = DivProps;
+/** Buttons at the end: one primary action, notifications, the account. Never wraps. */
+declare function AppHeaderActions({ className, ...rest }: AppHeaderActionsProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderActions {
+    var displayName: string;
+}
+export type AppHeaderMenuButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
+    /**
+     * `narrow` (default): shown below 768px, where an `offCanvas="auto"` Sidebar leaves the layout;
+     * `always`: on every width (`offCanvas="always"`).
+     */
+    show?: "narrow" | "always";
+    ref?: React.Ref<HTMLButtonElement>;
+};
+/** Opens the off-canvas Sidebar: an icon button named by `labels.menu`; wire `onClick` and `aria-expanded`. */
+declare function AppHeaderMenuButton({ show, className, ...rest }: AppHeaderMenuButtonProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppHeaderMenuButton {
+    var displayName: string;
+}
+export declare const AppHeader: {
+    Root: typeof AppHeaderRoot;
+    Start: typeof AppHeaderStart;
+    Title: typeof AppHeaderTitle;
+    Icon: typeof AppHeaderIcon;
+    Description: typeof AppHeaderDescription;
+    Separator: typeof AppHeaderSeparator;
+    Search: typeof AppHeaderSearch;
+    Actions: typeof AppHeaderActions;
+    MenuButton: typeof AppHeaderMenuButton;
+};
+export {};

package/dist/layout/app-shell/AppShell.d.ts

@@ -1,46 +1,71 @@
 import * as React from "react";
 export type AppShellRootProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
     /** Viewport-high shell: only `AppShell.Main` scrolls. Otherwise the document scrolls. */
     fillViewport?: boolean;
 };
-export type AppShellNavProps = React.HTMLAttributes<HTMLDivElement>;
+export type AppShellNavProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
+};
 /** Navigation column (usually `Sidebar.Root`); sits on the canvas. */
 declare function AppShellNav({ className, ...rest }: AppShellNavProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AppShellNav {
     var displayName: string;
 }
-export type AppShellHeaderProps = React.HTMLAttributes<HTMLElement>;
+/**
+ * Grid: navigation column | content panel. Everything that is not `AppShell.Nav` goes into the
+ * content panel (`bg-surface`, inset from the window on wide screens).
+ */
+declare function AppShellRoot({ fillViewport, className, children, ...rest }: AppShellRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppShellRoot {
+    var displayName: string;
+}
+export type AppShellFooterProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
+};
+/** Bottom bar of the content panel (`BottomNav` on a narrow shell). Sticky. */
+declare function AppShellFooter({ className, ...rest }: AppShellFooterProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppShellFooter {
+    var displayName: string;
+}
 /** `full` (default): the whole panel with responsive gutters; `contained`: centered, up to `--prime-layout-content-max-width` (long-read pages). */
 export type AppShellContentWidth = "contained" | "full";
 export type AppShellMainProps = React.HTMLAttributes<HTMLElement> & {
+    ref?: React.Ref<HTMLElement>;
     contentWidth?: AppShellContentWidth;
 };
-export type AppShellTemplateProps = Omit<AppShellRootProps, "children"> & {
+/** `<main>` with the canonical gutters; scrolls inside the panel when `fillViewport` is set. */
+declare function AppShellMain({ contentWidth, className, children, ...rest }: AppShellMainProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppShellMain {
+    var displayName: string;
+}
+export type AppShellTemplateProps = Omit<AppShellRootProps, "children" | "ref"> & {
+    /** Forwarded to the `<main>`. */
+    ref?: React.Ref<HTMLElement>;
     /** Navigation column content, usually `Sidebar.Root`. */
     nav?: React.ReactNode;
-    /** `AppShell.Header` content; no header row when omitted. */
+    /** The top bar of the content panel, an `AppHeader.Root`; no header when omitted. */
     header?: React.ReactNode;
+    /** `AppShell.Footer` content (`BottomNav`); no footer when omitted. */
+    footer?: React.ReactNode;
     children?: React.ReactNode;
-    mainProps?: Omit<AppShellMainProps, "children">;
+    mainProps?: Omit<AppShellMainProps, "children" | "ref">;
+    /** Main scrolls back to the top whenever this value changes (pass the router pathname). */
+    scrollResetKey?: unknown;
 };
+/**
+ * Root + Nav + the header + Main + Footer in one; main scrolls to the top when `scrollResetKey`
+ * changes.
+ */
+declare function AppShellTemplate({ ref, nav, header, footer, children, mainProps, scrollResetKey, ...rootProps }: AppShellTemplateProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AppShellTemplate {
+    var displayName: string;
+}
 export declare const AppShell: {
-    Root: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
-        /** Viewport-high shell: only `AppShell.Main` scrolls. Otherwise the document scrolls. */
-        fillViewport?: boolean;
-    } & React.RefAttributes<HTMLDivElement>>;
+    Root: typeof AppShellRoot;
     Nav: typeof AppShellNav;
-    Header: React.ForwardRefExoticComponent<AppShellHeaderProps & React.RefAttributes<HTMLElement>>;
-    Main: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
-        contentWidth?: AppShellContentWidth;
-    } & React.RefAttributes<HTMLElement>>;
-    Template: React.ForwardRefExoticComponent<Omit<AppShellRootProps, "children"> & {
-        /** Navigation column content, usually `Sidebar.Root`. */
-        nav?: React.ReactNode;
-        /** `AppShell.Header` content; no header row when omitted. */
-        header?: React.ReactNode;
-        children?: React.ReactNode;
-        mainProps?: Omit<AppShellMainProps, "children">;
-    } & React.RefAttributes<HTMLElement>>;
+    Main: typeof AppShellMain;
+    Footer: typeof AppShellFooter;
+    Template: typeof AppShellTemplate;
 };
 export {};
-//# sourceMappingURL=AppShell.d.ts.map

package/dist/layout/bottom-nav/BottomNav.d.ts

@@ -0,0 +1,80 @@
+import * as React from "react";
+import type { PaletteColor, Variant } from "@/internal/states";
+export type BottomNavLabels = {
+    /** `aria-label` of the `<nav>` landmark. */
+    nav: string;
+};
+export type BottomNavRootProps = React.HTMLAttributes<HTMLElement> & {
+    /** Icons without visible labels; the labels still name the items for screen readers. */
+    iconOnly?: boolean;
+    /**
+     * A glass capsule floating over the content (backdrop blur, inset from the edges) instead of
+     * a flat bar at the edge. It places itself at the bottom of its positioned container
+     * (`AppShell.Footer`), so the page scrolls under it.
+     */
+    floating?: boolean;
+    labels?: Partial<BottomNavLabels>;
+    /** The `<nav>` bar. */
+    ref?: React.Ref<HTMLElement>;
+};
+/**
+ * Phone navigation: a bar of 3–5 sections at the bottom of the screen. Inside `AppShell.Footer`
+ * it shows only while the content panel is narrower than 640px; wider, Sidebar navigates.
+ */
+declare function BottomNavRoot({ iconOnly, floating, labels, className, ...rest }: BottomNavRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace BottomNavRoot {
+    var displayName: string;
+}
+export type BottomNavItemIconProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
+    children: React.ReactNode;
+    ref?: React.Ref<HTMLSpanElement>;
+};
+/** The item glyph above the label. */
+declare function BottomNavItemIcon({ className, ...rest }: BottomNavItemIconProps): import("react/jsx-runtime").JSX.Element;
+declare namespace BottomNavItemIcon {
+    var displayName: string;
+}
+export type BottomNavItemCountProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children" | "color"> & {
+    /** The number (or a short status). */
+    children: React.ReactNode;
+    /** Badge hue. Default `red`: a count on a section asks for attention. */
+    color?: PaletteColor;
+    /** Badge treatment. Default `solid`. */
+    variant?: Exclude<Variant, "ghost">;
+    /** The Badge `<span>`. */
+    ref?: React.Ref<HTMLSpanElement>;
+};
+/** A count on the corner of the icon: a small Badge, read after the label. */
+declare function BottomNavItemCount({ color, variant, className, ...rest }: BottomNavItemCountProps): import("react/jsx-runtime").JSX.Element;
+declare namespace BottomNavItemCount {
+    var displayName: string;
+}
+type BottomNavItemOwnProps = {
+    /** Current section: `aria-current="page"`. Links rendered by a router may set it themselves. */
+    current?: boolean;
+    disabled?: boolean;
+    /** Render the single child element (a router link) as the item; its children are the content. */
+    asChild?: boolean;
+    /** `BottomNav.ItemIcon`, an optional `BottomNav.ItemCount` and the label. */
+    children?: React.ReactNode;
+};
+export type BottomNavItemProps = BottomNavItemOwnProps & Omit<React.ComponentPropsWithoutRef<"button">, keyof BottomNavItemOwnProps> & {
+    /** Renders an `<a>` instead of a `<button>`. */
+    href?: string;
+    target?: string;
+    rel?: string;
+    /** The `<a>`, `<button>` or the `asChild` element. */
+    ref?: React.Ref<HTMLElement>;
+};
+/** A section of the bar: the icon above a short label, both in the primary color while current. */
+declare function BottomNavItem({ current, disabled, asChild, href, className, children, onClick, type, ref, ...rest }: BottomNavItemProps): import("react/jsx-runtime").JSX.Element;
+declare namespace BottomNavItem {
+    var displayName: string;
+}
+export declare const BottomNav: {
+    Root: typeof BottomNavRoot;
+    Item: typeof BottomNavItem;
+    ItemIcon: typeof BottomNavItemIcon;
+    ItemCount: typeof BottomNavItemCount;
+};
+export {};

package/dist/layout/index.d.ts

@@ -1,5 +1,8 @@
-export type { AppShellContentWidth, AppShellHeaderProps, AppShellMainProps, AppShellNavProps, AppShellRootProps, AppShellTemplateProps, } from "./app-shell/AppShell";
+export type { AppHeaderActionsProps, AppHeaderDescriptionProps, AppHeaderIconProps, AppHeaderLabels, AppHeaderMenuButtonProps, AppHeaderRootProps, AppHeaderSearchProps, AppHeaderSeparatorProps, AppHeaderStartProps, AppHeaderTitleProps, } from "./app-header/AppHeader";
+export { AppHeader } from "./app-header/AppHeader";
+export type { AppShellContentWidth, AppShellFooterProps, AppShellMainProps, AppShellNavProps, AppShellRootProps, AppShellTemplateProps, } from "./app-shell/AppShell";
 export { AppShell } from "./app-shell/AppShell";
-export type { SidebarContentProps, SidebarFooterProps, SidebarGroupProps, SidebarHeaderProps, SidebarItemProps, SidebarLabels, SidebarMode, SidebarRootProps, SidebarToggleProps, } from "./sidebar/Sidebar";
+export type { BottomNavItemCountProps, BottomNavItemIconProps, BottomNavItemProps, BottomNavLabels, BottomNavRootProps, } from "./bottom-nav/BottomNav";
+export { BottomNav } from "./bottom-nav/BottomNav";
+export type { SidebarAccountProps, SidebarBrandLogoProps, SidebarBrandProps, SidebarContentProps, SidebarFooterProps, SidebarGroupProps, SidebarHeaderProps, SidebarItemActionProps, SidebarItemCountProps, SidebarItemIconProps, SidebarItemProps, SidebarItemShortcutProps, SidebarLabels, SidebarMode, SidebarRootProps, SidebarSubContentProps, SidebarSubProps, SidebarSubTriggerProps, SidebarToggleProps, } from "./sidebar/Sidebar";
 export { Sidebar, useSidebar } from "./sidebar/Sidebar";
-//# sourceMappingURL=index.d.ts.map