@pk-design/react-tailwind 1.8.1 → 1.10.0

package/dist/types/components/BottomNavigation/BottomNavigation.d.ts

@@ -1,5 +1,5 @@
 import type { BottomNavigationProps } from './BottomNavigation.types';
-export declare function BottomNavigation({ items, activeId, onChange, fixed, showLabels, theme, activeIndicatorStyle, containerClass, itemClass, }: BottomNavigationProps): import("react/jsx-runtime").JSX.Element;
+export declare function BottomNavigation({ items, activeId, onChange, fixed, showLabels, theme, activeIndicatorStyle, containerClass, itemClass, linkAs, linkHrefProp, ariaLabel, hidden, }: BottomNavigationProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace BottomNavigation {
     var displayName: string;
 }

package/dist/types/components/BottomNavigation/BottomNavigation.types.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import type { ElementType, ReactNode } from 'react';
 export type BottomNavigationLabelVisibility = 'always' | 'active' | 'never';
 export type BottomNavigationTheme = 'primary' | 'dark' | 'light';
 export interface BottomNavigationItem {
@@ -18,14 +18,19 @@ export interface BottomNavigationItem {
     disabled?: boolean;
     /** Custom click handler */
     onClick?: () => void;
+    /**
+     * Destination for a navigation tab. When set, the item renders as a link
+     * (`linkAs`) instead of a button, so it opens in a new tab and is announced as a link.
+     */
+    href?: string;
 }
 export interface BottomNavigationProps {
     /** Array of bottom navigation items (3 to 5 recommended) */
     items: BottomNavigationItem[];
     /** Controlled active tab ID */
     activeId: string;
-    /** Callback fired when a tab is selected */
-    onChange: (id: string) => void;
+    /** Callback fired when a tab is selected (optional when items navigate via `href`) */
+    onChange?: (id: string) => void;
     /** Fixed positioning at bottom of viewport (default: true) */
     fixed?: boolean;
     /** Controls when tab labels are visible ('always' | 'active' | 'never', default: 'always') */
@@ -38,4 +43,24 @@ export interface BottomNavigationProps {
     containerClass?: string;
     /** Tab button item class string */
     itemClass?: string;
+    /**
+     * Element or component used for items with an `href`, e.g. a router's `Link`.
+     * @default 'a'
+     */
+    linkAs?: ElementType;
+    /**
+     * Prop name `linkAs` takes the destination on ('to' for react-router's `Link`).
+     * @default 'href'
+     */
+    linkHrefProp?: 'href' | 'to';
+    /**
+     * Accessible name of the navigation landmark.
+     * @default 'Bottom Navigation'
+     */
+    ariaLabel?: string;
+    /**
+     * Removes the bar from the tree (not just visually), e.g. while a full-screen task owns the bottom edge.
+     * @default false
+     */
+    hidden?: boolean;
 }

package/dist/types/components/Button/Button.types.d.ts

@@ -85,23 +85,27 @@ export interface ButtonBaseProps {
      */
     loadingText?: string;
     /**
-     * Applies 50% border radius, producing a pill-shaped button.
+     * Applies a fully rounded border radius, producing a pill-shaped button
+     * (or a circle when combined with `iconOnly`).
      * @default false
      */
     rounded?: boolean;
     /**
-     * Indicates that the button only contains an icon.
+     * Indicates that the button only contains an icon. Requires `aria-label`
+     * or `aria-labelledby` so the button has an accessible name.
      * @default false
      */
     iconOnly?: boolean;
     /**
-     * Prevents outline styles on keyboard focus.
+     * Removes the focus ring shown on keyboard focus. Only use this when the
+     * button gets another visible focus indicator, e.g. via `className`.
      * @default false
      */
     noOutlineOnFocus?: boolean;
     /**
-     * Indicates active toggle state (applies aria-pressed).
-     * @default false
+     * Turns the button into a toggle: when set to `true` or `false`,
+     * `aria-pressed` reflects it and `true` shows a ring. Leave unset for a
+     * regular (non-toggle) button.
      */
     active?: boolean;
     /**
@@ -113,7 +117,9 @@ export interface ButtonBaseProps {
      */
     type?: 'button' | 'submit' | 'reset';
     /**
-     * Standard disabled attribute. Only applies when as="button".
+     * Disables the button. Rendered as the native `disabled` attribute on
+     * `<button>`, or as `aria-disabled` (with `tabIndex={-1}` and clicks
+     * blocked) for any other element passed via `as`.
      */
     disabled?: boolean;
 }

package/dist/types/components/Drawer/Drawer.types.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from 'react';
+import type { ResponsiveValue } from '../../hooks/use-breakpoint';
 export type DrawerAlignment = 'center' | 'start' | 'end' | 'top' | 'bottom';
 export type DrawerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
 export interface DrawerProps {
@@ -17,10 +18,12 @@ export interface DrawerProps {
      */
     closeOnOutsideClick?: boolean;
     /**
-     * Drawer alignment on the page ('start' | 'end' | 'top' | 'bottom' | 'center')
+     * Drawer alignment on the page ('start' | 'end' | 'top' | 'bottom' | 'center').
+     * Pass `{ base, md, lg }` to change it per breakpoint, e.g. `{ base: 'bottom', md: 'end' }`
+     * for a bottom sheet on phones and a side panel from 768px.
      * @default "end"
      */
-    align?: DrawerAlignment;
+    align?: ResponsiveValue<DrawerAlignment>;
     /**
      * Whether to add backdrop overlay
      * @default true
@@ -52,10 +55,11 @@ export interface DrawerProps {
      */
     footerSticky?: boolean;
     /**
-     * Drawer size ('xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full')
+     * Drawer size ('xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full').
+     * Pass `{ base, md, lg }` to change it per breakpoint, e.g. `{ base: 'full', md: 'md' }`.
      * @default "md"
      */
-    size?: DrawerSize;
+    size?: ResponsiveValue<DrawerSize>;
     /**
      * Shows top-right ✕ close button
      * @default true

package/dist/types/components/MobileHeader/MobileHeader.d.ts

@@ -1,5 +1,5 @@
 import type { MobileHeaderProps } from './MobileHeader.types';
-export declare function MobileHeader({ title, subtitle, titleAlign, onBack, backLabel, leading, actions, searchable, searchValue: externalSearchValue, onSearchChange, searchPlaceholder, sticky, transparent, bottomSlot, className, }: MobileHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function MobileHeader({ title, subtitle, titleAlign, onBack, backLabel, leading, actions, maxVisibleActions, overflowLabel, trailing, searchable, searchValue: externalSearchValue, onSearchChange, searchPlaceholder, sticky, transparent, bottomSlot, className, }: MobileHeaderProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace MobileHeader {
     var displayName: string;
 }

package/dist/types/components/MobileHeader/MobileHeader.types.d.ts

@@ -30,6 +30,19 @@ export interface MobileHeaderProps {
     leading?: ReactNode;
     /** Right side action items */
     actions?: MobileHeaderAction[];
+    /**
+     * Maximum icon buttons shown in the header. When `actions` has more, the
+     * extras collapse into a "More actions" button that opens an `ActionSheet`.
+     * Unset shows every action.
+     */
+    maxVisibleActions?: number;
+    /**
+     * Accessible label of the overflow button.
+     * @default 'More actions'
+     */
+    overflowLabel?: string;
+    /** Custom content after the actions, e.g. an avatar or a context switcher with its own state */
+    trailing?: ReactNode;
     /** Enables in-header search bar layout */
     searchable?: boolean;
     /** Controlled search input value */

package/dist/types/components/PullToRefresh/PullToRefresh.d.ts

@@ -1,5 +1,5 @@
 import type { PullToRefreshProps } from './PullToRefresh.types';
-export declare function PullToRefresh({ onRefresh, pullThreshold, maxPullDistance, disabled, refreshing: externalRefreshing, pullingContent, refreshingContent, children, className, contentClass, }: PullToRefreshProps): import("react/jsx-runtime").JSX.Element;
+export declare function PullToRefresh({ onRefresh, onError, variant, pullThreshold, maxPullDistance, disabled, refreshing: externalRefreshing, pullingContent, refreshingContent, pullLabel, releaseLabel, refreshingLabel, refreshedLabel, children, className, contentClass, }: PullToRefreshProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace PullToRefresh {
     var displayName: string;
 }

package/dist/types/components/PullToRefresh/PullToRefresh.types.d.ts

@@ -1,19 +1,58 @@
 import type { ReactNode } from 'react';
+/**
+ * - `push`: a labelled pill opens above the content, which moves down with the pull.
+ * - `overlay`: the content stays still; a round badge slides down over it (e.g. from
+ *   behind a sticky app header) and parks at the threshold while refreshing.
+ */
+export type PullToRefreshVariant = 'push' | 'overlay';
 export interface PullToRefreshProps {
-    /** Async callback function triggered when user pulls to refresh */
-    onRefresh: () => Promise<void> | void;
-    /** Pull distance threshold in px to trigger refresh (default: 70) */
+    /** Callback triggered when the user pulls past the threshold; return a promise to keep the indicator until it settles */
+    onRefresh: () => Promise<unknown> | void;
+    /** Called when `onRefresh` throws or rejects, so the failure can be shown instead of lost */
+    onError?: (error: unknown) => void;
+    /**
+     * Indicator style
+     * @default 'push'
+     */
+    variant?: PullToRefreshVariant;
+    /**
+     * Pull distance in px (after resistance) that triggers a refresh
+     * @default 70
+     */
     pullThreshold?: number;
-    /** Maximum pull distance in px (default: 120) */
+    /**
+     * Maximum pull distance in px
+     * @default 120
+     */
     maxPullDistance?: number;
     /** Disables the pull-to-refresh touch gesture */
     disabled?: boolean;
     /** Controlled refreshing state */
     refreshing?: boolean;
-    /** Custom content rendered while pulling down */
+    /** Custom content rendered while pulling down (replaces the default indicator content) */
     pullingContent?: ReactNode;
-    /** Custom content rendered while refreshing */
+    /** Custom content rendered while refreshing (replaces the default indicator content) */
     refreshingContent?: ReactNode;
+    /**
+     * Indicator text before the threshold is reached (`push` variant)
+     * @default 'Pull down to refresh'
+     */
+    pullLabel?: string;
+    /**
+     * Indicator text once releasing will refresh (`push` variant)
+     * @default 'Release to refresh'
+     */
+    releaseLabel?: string;
+    /**
+     * Indicator text and screen-reader announcement while refreshing
+     * @default 'Refreshing...'
+     */
+    refreshingLabel?: string;
+    /**
+     * Screen-reader announcement once a refresh finishes
+     * @default 'Content refreshed'
+     */
+    refreshedLabel?: string;
     /** Main scrollable content node */
     children: ReactNode;
     /** Container class string */

package/dist/types/components/SelectBox/SelectBox.types.d.ts

@@ -22,11 +22,21 @@ export interface SelectBoxProps<T extends BaseOption | string = BaseOption> {
     /** List of option groups to display in the dropdown (alternative to options) */
     groups?: OptionGroup<T>[];
     /**
-     * Currently selected option(s).
+     * Currently selected option(s). Passing this makes the SelectBox controlled:
+     * it shows exactly this value, so update it from `onChange`.
      * - For single select: a single T or null
      * - For multi-select: T[]
+     *
+     * Leave it undefined to let the SelectBox manage its own selection
+     * (optionally seeded with `defaultSelected`).
      */
     selected?: T | T[] | null;
+    /**
+     * Initial selection when the SelectBox is uncontrolled (`selected` not passed).
+     * Only read on mount; later changes are ignored. `onChange` still fires on
+     * every change.
+     */
+    defaultSelected?: T | T[] | null;
     /** Size scale of the SelectBox component (`"sm"` | `"md"` | `"lg"`). Defaults to `"md"`. */
     size?: SelectBoxSize;
     /** Name of the field inside option objects to use as the label (defaults to "label") */
@@ -59,6 +69,13 @@ export interface SelectBoxProps<T extends BaseOption | string = BaseOption> {
     placeholder?: string;
     /** CSS classes applied to the dropdown options container */
     dropdownContainerClass?: string;
+    /**
+     * Minimum width of the dropdown panel. By default the panel matches the
+     * input width; set this so it can grow wider than a narrow input. Numbers
+     * are treated as pixels, strings accept any CSS length (e.g. `"16rem"`).
+     * The panel stays left-aligned with the input.
+     */
+    dropdownMinWidth?: number | string;
     /**
      * Whether the open dropdown traps focus and makes the rest of the page inert.
      * @default false

package/dist/types/components/StickyActionBar/StickyActionBar.types.d.ts

@@ -27,4 +27,16 @@ export interface StickyActionBarProps extends HTMLAttributes<HTMLDivElement> {
      * @default "max-w-5xl"
      */
     containerMaxWidth?: string;
+    /**
+     * Pads the bar's bottom edge for `env(safe-area-inset-bottom)` so its actions clear the
+     * home indicator on notched phones (no effect elsewhere).
+     * @default true
+     */
+    safeArea?: boolean;
+    /**
+     * Distance from the viewport bottom for `fixed`/`sticky` bars, as a CSS length or variable,
+     * e.g. `var(--app-bottom-inset)` to sit above an app's bottom navigation.
+     * @default '0px'
+     */
+    bottomOffset?: string;
 }

package/dist/types/hooks/use-breakpoint.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Layout ranges matching Tailwind's `md` (768px) and `lg` (1024px) tokens, so a
+ * JS decision and an `md:`/`lg:` class always agree:
+ * - `compact`: phones
+ * - `medium`: tablets and narrow windows
+ * - `expanded`: desktop
+ *
+ * Width only. Unlike `useIsMobile`, touch capability is never considered, so a
+ * phone in landscape and a narrow desktop window get the layout for their size.
+ */
+export type Breakpoint = 'compact' | 'medium' | 'expanded';
+export declare const BREAKPOINT_QUERIES: {
+    readonly medium: "(min-width: 768px)";
+    readonly expanded: "(min-width: 1024px)";
+};
+/** Live result of a CSS media query. `false` during server rendering or without `matchMedia`. */
+export declare const useMediaQuery: (query: string) => boolean;
+/** Current layout range; `compact` during server rendering. */
+export declare const useBreakpoint: () => Breakpoint;
+/** A value per breakpoint; missing ranges fall back to the next smaller one. */
+export type ResponsiveValue<T> = T | {
+    base: T;
+    md?: T;
+    lg?: T;
+};
+/** Resolves a `ResponsiveValue` for the current viewport. */
+export declare const useResponsiveValue: <T>(value: ResponsiveValue<T>) => T;

package/dist/types/hooks/use-breakpoint.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -54,6 +54,7 @@ export * from './components/Textarea';
 export * from './components/Toast';
 export * from './components/VirtualizedDataTable';
 export * from './components/common-type';
+export * from './hooks/use-breakpoint';
 export * from './hooks/use-debounce';
 export * from './hooks/use-is-mobile';
 export * from './hooks/use-is-tablet';

package/dist/types/test-utils/mock-viewport.d.ts

@@ -0,0 +1,7 @@
+export declare function mockViewport(initialWidth: number): {
+    resize(next: number): void;
+    listenerCount: () => number;
+};
+export declare namespace mockViewport {
+    var restore: () => void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pk-design/react-tailwind",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "main": "dist/react-tailwind.cjs.js",
   "module": "dist/react-tailwind.es.js",
   "types": "dist/types/index.d.ts",