@sito/ui 0.1.6 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2021 Sito Nimbus
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2021 Sito Nimbus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,2 +1,88 @@
-# @sito/ui
-React library for easy front end development
+# @sito/ui
+
+Low-level React UI primitives for Sito packages and apps.
+
+## Install Styles
+
+Styles are optional. Import the full stylesheet when you want the default theme
+and component styles:
+
+```ts
+import "@sito/ui/styles.css";
+```
+
+Import only the theme variables when you want to provide component CSS yourself:
+
+```ts
+import "@sito/ui/theme.css";
+```
+
+## Public API
+
+```ts
+import { Button, Dialog, DialogActions, IconButton, useDialog } from "@sito/ui";
+```
+
+Exported types include `ButtonProps`, `ButtonSize`, `IconButtonProps`,
+`DialogProps`, `DialogActionsProps`, `DialogState`, `IconButtonSize`, and
+`UseDialogReturn`.
+
+## Button Sizes
+
+`Button` supports `size="sm" | "md" | "lg"` for padding and height. `md` is
+the default size.
+
+```tsx
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
+```
+
+## Icon Button Sizes
+
+`IconButton` supports `size="sm" | "md" | "lg"` for the button container.
+`md` is the default size.
+
+```tsx
+<IconButton aria-label="Add" icon="+" size="sm" />
+<IconButton aria-label="Add" icon="+" size="md" />
+<IconButton aria-label="Add" icon="+" size="lg" />
+```
+
+The container sizes are `28px`, `40px`, and `48px`. Icon size is separate:
+override `iconSize` or `--sito-ui-icon-button-icon-size`.
+
+## Development
+
+Run the component test suite with:
+
+```sh
+pnpm test:run
+```
+
+Start Storybook with:
+
+```sh
+pnpm storybook
+```
+
+## Dialog Exit Transitions
+
+`Dialog` unmounts immediately by default. Pass `exitDurationMs` when a consumer
+needs to keep the portal mounted long enough for a CSS exit animation:
+
+```tsx
+<Dialog open={open} onClose={close} exitDurationMs={220}>
+  Dialog content
+</Dialog>
+```
+
+During that delay, the backdrop and dialog expose `data-state="closing"` plus
+`sito-ui-dialog-backdrop--closing` and `sito-ui-dialog--closing` classes.
+Use those hooks from consumer CSS to define the actual animation.
+
+## Scope
+
+This package only exposes generic primitives. It does not include dashboard
+workflows, forms, translations, icon packs, routing, storage, providers, or data
+fetching.

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

@@ -1,4 +1,3 @@
-/// <reference types="react" />
-import { ButtonProps } from "./types";
-declare const Button: import("react").ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+import { ButtonProps } from './types';
+declare const Button: import('react').ForwardRefExoticComponent<ButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
 export default Button;

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

@@ -1,3 +1,3 @@
-import Button from "./Button";
+import { default as Button } from './Button';
+export type { ButtonBaseProps, ButtonColor, ButtonProps, ButtonSize, ButtonVariant, } from './types';
 export { Button };
-export * from "./types";

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

@@ -1,8 +1,35 @@
-import { HTMLProps } from "react";
-import { ColorVariants } from '../../providers/StyleProvider/types';
-export type ButtonShapes = "filled" | "outlined" | "text";
-export interface ButtonProps extends Omit<HTMLProps<HTMLButtonElement>, "size"> {
-    color?: ColorVariants | undefined;
-    shape?: ButtonShapes | undefined;
+import { ButtonHTMLAttributes, ReactNode } from 'react';
+export declare const BUTTON_COLOR_VARIANTS: {
+    readonly DEFAULT: "default";
+    readonly PRIMARY: "primary";
+    readonly SECONDARY: "secondary";
+    readonly ERROR: "error";
+    readonly WARNING: "warning";
+    readonly SUCCESS: "success";
+    readonly INFO: "info";
+};
+export declare const BUTTON_VARIANTS: {
+    readonly TEXT: "text";
+    readonly SUBMIT: "submit";
+    readonly OUTLINED: "outlined";
+};
+export declare const BUTTON_SIZES: {
+    readonly SM: "sm";
+    readonly MD: "md";
+    readonly LG: "lg";
+};
+export type ButtonColor = (typeof BUTTON_COLOR_VARIANTS)[keyof typeof BUTTON_COLOR_VARIANTS];
+export type ButtonSize = (typeof BUTTON_SIZES)[keyof typeof BUTTON_SIZES];
+export type ButtonVariant = (typeof BUTTON_VARIANTS)[keyof typeof BUTTON_VARIANTS];
+export type ButtonBaseProps = {
+    color?: ButtonColor | undefined;
+    size?: ButtonSize | undefined;
+    variant?: ButtonVariant | undefined;
+    loading?: boolean | undefined;
+    loadingIndicator?: ReactNode;
+    loadingLabel?: string | undefined;
+    [key: `data-${string}`]: string | number | boolean | undefined;
+};
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "color" | "type">, ButtonBaseProps {
     type?: "button" | "submit" | "reset" | undefined;
 }

package/dist/components/Dialog/Dialog.d.ts

@@ -0,0 +1,7 @@
+import { DialogProps } from './types';
+/**
+ * Renders an accessible modal dialog in a portal.
+ * @param props Dialog configuration and content.
+ * @returns The dialog portal when open, otherwise null.
+ */
+export declare const Dialog: (props: DialogProps) => import('react').ReactPortal | null;

package/dist/components/Dialog/DialogActions.d.ts

@@ -0,0 +1,7 @@
+import { DialogActionsProps } from './types';
+/**
+ * Renders primary, extra, and cancel actions for a dialog.
+ * @param props Action labels, handlers, and button state.
+ * @returns The dialog actions container.
+ */
+export declare const DialogActions: (props: DialogActionsProps) => import("react").JSX.Element;

package/dist/components/Dialog/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const focusableInputSelector = "input:not([type=\"hidden\"]):not([disabled]), textarea:not([disabled]), select:not([disabled])";
+export declare const submitSelector = "button[type=\"submit\"]:not([disabled]), input[type=\"submit\"]:not([disabled])";
+export declare const focusableSelector: string;

package/dist/components/Dialog/index.d.ts

@@ -0,0 +1,3 @@
+export { Dialog } from './Dialog';
+export { DialogActions } from './DialogActions';
+export type { DialogActionButtonProps, DialogActionsProps, DialogInitialFocus, DialogProps, DialogState, DialogSubmitHandler, } from './types';

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

@@ -0,0 +1,61 @@
+import { FormEvent, ReactNode } from 'react';
+import { ButtonProps } from '../Button';
+export declare const DIALOG_INITIAL_FOCUS: {
+    readonly NONE: "none";
+    readonly FIRST_INPUT: "first-input";
+    readonly SUBMIT: "submit";
+};
+export type DialogInitialFocus = (typeof DIALOG_INITIAL_FOCUS)[keyof typeof DIALOG_INITIAL_FOCUS];
+export type DialogState = "open" | "closing";
+export type DialogSubmitHandler = (event: FormEvent<HTMLFormElement>) => void | Promise<void>;
+type DialogAccessibleNameProps = {
+    title: ReactNode;
+    ariaLabel?: string;
+} | {
+    title?: undefined;
+    ariaLabel: string;
+};
+type DialogBaseProps = {
+    dialogId?: string;
+    open?: boolean;
+    children?: ReactNode;
+    onClose: () => void;
+    initialFocus?: DialogInitialFocus;
+    closeOnBackdropClick?: boolean;
+    closeOnEscape?: boolean;
+    lockBodyScroll?: boolean;
+    onSubmit?: DialogSubmitHandler;
+    mobileFullScreen?: boolean;
+    containerClassName?: string;
+    className?: string;
+    closeLabel?: string;
+    closeIcon?: ReactNode;
+    showCloseButton?: boolean;
+    portalContainer?: Element | DocumentFragment | null;
+    exitDurationMs?: number;
+    onExitComplete?: () => void;
+};
+export type DialogProps = DialogBaseProps & DialogAccessibleNameProps;
+export type DialogActionButtonProps = ButtonProps & {
+    id: string;
+};
+export type DialogActionsProps = {
+    primaryText: ReactNode;
+    cancelText: ReactNode;
+    onPrimaryClick?: () => void;
+    onCancel: () => void;
+    isLoading?: boolean;
+    loadingIndicator?: ReactNode;
+    disabled?: boolean;
+    primaryType?: "button" | "submit" | "reset";
+    containerClassName?: string;
+    primaryClassName?: string;
+    cancelClassName?: string;
+    alignEnd?: boolean;
+    primaryName?: string;
+    primaryAriaLabel?: string;
+    cancelName?: string;
+    cancelAriaLabel?: string;
+    extraActions?: DialogActionButtonProps[];
+};
+export {};

package/dist/components/Dialog/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Prevents document body scrolling while a dialog is open.
+ */
+export declare const lockBodyScroll: () => void;
+/**
+ * Restores document body scrolling after dialogs close.
+ */
+export declare const unlockBodyScroll: () => void;
+/**
+ * Finds enabled focusable descendants inside an element.
+ * @param element Root element to search inside.
+ * @returns Focusable descendants that are not aria-disabled.
+ */
+export declare const getFocusableElements: (element: HTMLElement) => HTMLElement[];
+/**
+ * Gets the active element when it is an HTMLElement.
+ * @returns Active HTMLElement, or null when unavailable.
+ */
+export declare const getActiveElement: () => HTMLElement | null;

package/dist/components/IconButton/IconButton.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="react" />
-import { IconButtonProps } from "./types";
-declare const IconButton: import("react").ForwardRefExoticComponent<Omit<IconButtonProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+import { IconButtonProps } from './types';
+declare const IconButton: import('react').ForwardRefExoticComponent<IconButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
 export default IconButton;

package/dist/components/IconButton/index.d.ts

@@ -1,3 +1,3 @@
-import IconButton from "./IconButton";
-export type { IconButtonProps } from "./types";
+import { default as IconButton } from './IconButton';
+export type { IconButtonProps, IconButtonSize } from './types';
 export { IconButton };

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

@@ -1,6 +1,22 @@
-import { ReactNode } from "react";
-import { ButtonProps } from '../Button/';
-export interface IconButtonProps extends ButtonProps {
+import { ReactNode } from 'react';
+import { ButtonProps } from '../Button';
+export declare const ICON_BUTTON_SIZES: {
+    readonly SM: "sm";
+    readonly MD: "md";
+    readonly LG: "lg";
+};
+export type IconButtonSize = (typeof ICON_BUTTON_SIZES)[keyof typeof ICON_BUTTON_SIZES];
+type IconButtonAccessibleLabelProps = {
+    "aria-label": string;
+    children?: ReactNode;
+} | {
+    "aria-label"?: string;
+    children: ReactNode;
+};
+export type IconButtonProps = Omit<ButtonProps, "aria-label" | "children" | "size"> & IconButtonAccessibleLabelProps & {
     icon: ReactNode;
-    size: "small" | "normal" | "large";
-}
+    iconClassName?: string;
+    iconSize?: number | string;
+    size?: IconButtonSize;
+};
+export {};

package/dist/components/index.d.ts

@@ -1,10 +1,6 @@
-export * from './Button/';
-export * from "./IconButton";
-export * from "./InputControl";
-export * from "./Switch/";
-export * from "./Image";
-export * from "./PrintAfter";
-export * from "./Notification";
-export * from "./Loading";
-export * from "./SplashScreen";
-export * from "./Error";
+export type { ButtonBaseProps, ButtonColor, ButtonProps, ButtonSize, ButtonVariant, } from './Button';
+export { Button } from './Button';
+export type { DialogActionButtonProps, DialogActionsProps, DialogInitialFocus, DialogProps, DialogState, DialogSubmitHandler, } from './Dialog';
+export { Dialog, DialogActions } from './Dialog';
+export type { IconButtonProps, IconButtonSize } from './IconButton';
+export { IconButton } from './IconButton';

package/dist/hooks/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./useIsElementInViewport";
-export * from "./useScreenHandler";
+export type { UseDialogReturn } from './useDialog';
+export { useDialog } from './useDialog';

package/dist/hooks/useDialog/index.d.ts

@@ -0,0 +1,2 @@
+export type { UseDialogReturn } from './types';
+export { useDialog } from './useDialog';

package/dist/hooks/useDialog/types.d.ts

@@ -0,0 +1,7 @@
+import { Dispatch, SetStateAction } from 'react';
+export type UseDialogReturn = {
+    open: boolean;
+    setOpen: Dispatch<SetStateAction<boolean>>;
+    handleOpen: () => void;
+    handleClose: () => void;
+};

package/dist/hooks/useDialog/useDialog.d.ts

@@ -0,0 +1,7 @@
+import { UseDialogReturn } from './types';
+/**
+ * Manages dialog open state and common open/close handlers.
+ * @param initialOpen Initial open state for the dialog.
+ * @returns Current state and helpers to update it.
+ */
+export declare const useDialog: (initialOpen?: boolean) => UseDialogReturn;

package/dist/main.d.ts

@@ -1,3 +1,4 @@
-export * from "./components";
-export * from "./providers";
-export * from "./hooks";
+export type { ButtonBaseProps, ButtonColor, ButtonProps, ButtonSize, ButtonVariant, DialogActionButtonProps, DialogActionsProps, DialogInitialFocus, DialogProps, DialogState, DialogSubmitHandler, IconButtonProps, IconButtonSize, } from './components';
+export { Button, Dialog, DialogActions, IconButton } from './components';
+export type { UseDialogReturn } from './hooks';
+export { useDialog } from './hooks';