@fpkit/acss 0.5.11 → 0.5.13

package/src/components/dialog/dialog.types.ts

@@ -0,0 +1,133 @@
+import { CSSProperties, ReactNode } from "react";
+
+/**
+ * Base properties shared by all dialog variants.
+ *
+ * @property {string} dialogTitle - The title displayed in the dialog header
+ * @property {string} [dialogLabel] - Optional accessible label for the dialog (aria-label)
+ * @property {ReactNode} children - Content to be displayed inside the dialog body
+ * @property {string} [className] - Additional CSS classes to apply to the dialog
+ * @property {CSSProperties} [styles] - Inline styles to apply to the dialog element
+ */
+export interface BaseDialogProps {
+  /** The title displayed in the dialog header */
+  dialogTitle: string;
+  /** Optional accessible label for the dialog (aria-label) */
+  dialogLabel?: string;
+  /** Content to be displayed inside the dialog body */
+  children: ReactNode;
+  /** Additional CSS classes to apply to the dialog */
+  className?: string;
+  /** Inline styles to apply to the dialog element */
+  styles?: CSSProperties;
+}
+
+/**
+ * Props for the controlled Dialog component.
+ * Use this when you want to manage dialog state externally.
+ *
+ * @extends BaseDialogProps
+ * @property {boolean} isOpen - Controls whether the dialog is currently open
+ * @property {(open: boolean) => void} onOpenChange - Callback fired when dialog open state should change
+ * @property {boolean} [isAlertDialog=false] - If true, renders as non-modal inline alert using dialog.show()
+ * @property {() => void} [onClose] - Deprecated: Use onOpenChange instead. Called when dialog closes.
+ * @property {() => void | Promise<void>} [onConfirm] - Callback fired when confirm button is clicked
+ * @property {string} [confirmLabel="Confirm"] - Text label for the confirm button
+ * @property {string} [cancelLabel="Cancel"] - Text label for the cancel button
+ * @property {boolean} [hideFooter=false] - If true, hides the dialog footer with action buttons
+ */
+export interface DialogProps extends BaseDialogProps {
+  /** Controls whether the dialog is currently open (controlled component) */
+  isOpen: boolean;
+  /** Callback fired when dialog open state should change */
+  onOpenChange: (open: boolean) => void;
+  /** If true, renders as non-modal inline alert using dialog.show() instead of dialog.showModal() */
+  isAlertDialog?: boolean;
+  /** @deprecated Use onOpenChange instead. Called when dialog closes. */
+  onClose?: () => void;
+  /** Callback fired when confirm button is clicked */
+  onConfirm?: () => void | Promise<void>;
+  /** Text label for the confirm button */
+  confirmLabel?: string;
+  /** Text label for the cancel button */
+  cancelLabel?: string;
+  /** If true, hides the dialog footer with action buttons */
+  hideFooter?: boolean;
+}
+
+/**
+ * Props for the DialogModal wrapper component.
+ * This component manages dialog state internally and provides a trigger button.
+ * Use this for simple cases where you don't need external state management.
+ *
+ * @extends BaseDialogProps
+ * @property {boolean} [isAlertDialog=false] - If true, renders as non-modal inline alert
+ * @property {() => void} [onClose] - Callback fired when dialog is closed
+ * @property {() => void | Promise<void>} [onConfirm] - Callback fired when confirm button is clicked
+ * @property {string} [confirmLabel="Confirm"] - Text label for the confirm button
+ * @property {string} [cancelLabel="Cancel"] - Text label for the cancel button
+ * @property {boolean} [hideFooter=false] - If true, hides the dialog footer
+ * @property {string} [btnLabel="Open Dialog"] - Text label for the trigger button
+ * @property {"sm" | "md" | "lg"} [btnSize="sm"] - Size variant for the trigger button
+ * @property {() => void} [btnOnClick] - Callback fired when trigger button is clicked (before opening)
+ */
+export interface DialogModalProps extends BaseDialogProps {
+  /** If true, renders as non-modal inline alert using dialog.show() */
+  isAlertDialog?: boolean;
+  /** Callback fired when dialog is closed */
+  onClose?: () => void;
+  /** Callback fired when confirm button is clicked */
+  onConfirm?: () => void | Promise<void>;
+  /** Text label for the confirm button */
+  confirmLabel?: string;
+  /** Text label for the cancel button */
+  cancelLabel?: string;
+  /** If true, hides the dialog footer with action buttons */
+  hideFooter?: boolean;
+  /** Text label for the trigger button that opens the dialog */
+  btnLabel?: string;
+  /** Size variant for the trigger button */
+  btnSize?: "sm" | "md" | "lg";
+  /** Callback fired when trigger button is clicked (before opening dialog) */
+  btnOnClick?: () => void;
+  /** Additional props to pass to the trigger button component */
+  btnProps?: Record<string, unknown>;
+}
+
+/**
+ * Props for the DialogHeader component.
+ *
+ * @property {string} dialogTitle - The title text to display in the header
+ * @property {() => void} onClick - Callback fired when the close button is clicked
+ * @property {string} [id] - Optional ID for aria-labelledby linking. Auto-generated if not provided.
+ * @property {"h1" | "h2" | "h3" | "h4" | "h5" | "h6"} [type="h3"] - Heading level for the title
+ */
+export interface DialogHeaderProps {
+  /** The title text to display in the header */
+  dialogTitle: string;
+  /** Callback fired when the close button is clicked */
+  onClick: () => void;
+  /** Optional ID for aria-labelledby linking. Auto-generated if not provided. */
+  id?: string;
+  /** Heading level for the title */
+  type?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+}
+
+/**
+ * Props for the DialogFooter component.
+ *
+ * @property {() => void} onClose - Callback fired when cancel button is clicked
+ * @property {() => void | Promise<void>} [onConfirm] - Callback fired when confirm button is clicked
+ * @property {string} confirmLabel - Text label for the confirm button
+ * @property {string} cancelLabel - Text label for the cancel button
+ */
+export interface DialogFooterProps {
+  /** Callback fired when cancel button is clicked */
+  onClose: () => void;
+  /** Callback fired when confirm button is clicked */
+  onConfirm?: () => void | Promise<void>;
+  /** Text label for the confirm button */
+  confirmLabel: string;
+  /** Text label for the cancel button */
+  cancelLabel: string;
+}

package/src/components/dialog/views/dialog-footer.tsx

@@ -1,26 +1,67 @@
-import React from "react";
+import React, { useCallback } from "react";
 import UI from "#components/ui";
 import Button from "#components/buttons/button";
+import type { DialogFooterProps } from "../dialog.types";
 
-type DialogFooterProps = {
-  onClose: () => void;
-  onConfirm?: () => void | Promise<void>;
-  confirmLabel: string;
-  cancelLabel: string;
-};
-
+/**
+ * DialogFooter component renders action buttons for dialog confirmation/cancellation.
+ *
+ * This component provides a consistent footer layout with:
+ * - Cancel button (secondary style) - Always shown if cancelLabel provided
+ * - Confirm button (primary style) - Only shown if onConfirm callback provided
+ * - Proper semantic button types
+ * - Accessible button sizing and spacing
+ * - Memoized to prevent unnecessary re-renders
+ *
+ * @component
+ * @param {DialogFooterProps} props - Component props
+ * @param {() => void} props.onClose - Callback fired when cancel button is clicked
+ * @param {() => void | Promise<void>} [props.onConfirm] - Optional callback for confirm action. If omitted, confirm button is hidden.
+ * @param {string} props.confirmLabel - Text label for the confirm button
+ * @param {string} props.cancelLabel - Text label for the cancel button
+ * @returns {JSX.Element} A footer section with action buttons
+ *
+ * @example
+ * ```tsx
+ * // Simple close-only footer
+ * <DialogFooter
+ *   onClose={() => setOpen(false)}
+ *   cancelLabel="Close"
+ *   confirmLabel="OK"
+ * />
+ *
+ * // Confirmation dialog with both actions
+ * <DialogFooter
+ *   onClose={() => setOpen(false)}
+ *   onConfirm={async () => await deleteItem()}
+ *   confirmLabel="Delete"
+ *   cancelLabel="Cancel"
+ * />
+ * ```
+ */
 const DialogFooter: React.FC<DialogFooterProps> = ({
   onClose,
   onConfirm,
   confirmLabel,
   cancelLabel,
 }) => {
+  // Memoize handlers to prevent unnecessary re-renders
+  const handleCancel = useCallback(() => {
+    onClose();
+  }, [onClose]);
+
+  const handleConfirm = useCallback(() => {
+    if (onConfirm) {
+      onConfirm();
+    }
+  }, [onConfirm]);
+
   return (
     <UI as="section" className="dialog-footer">
       {cancelLabel && (
         <Button
           type="button"
-          onClick={onClose}
+          onClick={handleCancel}
           className="dialog-button button-secondary"
           data-btn="sm"
         >
@@ -31,7 +72,7 @@ const DialogFooter: React.FC<DialogFooterProps> = ({
       {onConfirm && (
         <Button
           type="button"
-          onClick={onConfirm}
+          onClick={handleConfirm}
           className="dialog-button button-primary"
           data-btn="sm"
         >
@@ -42,4 +83,6 @@ const DialogFooter: React.FC<DialogFooterProps> = ({
   );
 };
 
-export default DialogFooter;
+DialogFooter.displayName = "DialogFooter";
+
+export default React.memo(DialogFooter);

package/src/components/dialog/views/dialog-header.tsx

@@ -1,45 +1,50 @@
-import React from "react";
+import React, { useCallback } from "react";
 import UI from "#components/ui";
 import Heading from "#components/heading/heading";
 import Button from "#components/buttons/button";
 import Icon from "#components/icons/icon";
-
-export type DialogHeaderProps = {
-  dialogTitle: string;
-  onClick: () => void;
-} & React.ComponentProps<typeof Heading>;
+import type { DialogHeaderProps } from "../dialog.types";
 
 /**
  * DialogHeader component displays the header section of a dialog with a title and close button.
  *
+ * This component is optimized for accessibility with:
+ * - Unique ID for `aria-labelledby` linking to parent dialog
+ * - Semantic heading structure for screen readers
+ * - Clear close button with accessible label
+ * - Memoized to prevent unnecessary re-renders
+ *
  * @component
- * @param {Object} props - Component props
+ * @param {DialogHeaderProps} props - Component props
  * @param {string} props.dialogTitle - The title text to display in the dialog header
  * @param {() => void} props.onClick - Callback function triggered when close button is clicked
- * @param {string} [props.type='h3'] - Heading type/level to use for the title
+ * @param {string} [props.id] - Optional ID for aria-labelledby linking. Auto-generated if not provided.
+ * @param {"h1" | "h2" | "h3" | "h4" | "h5" | "h6"} [props.type="h3"] - Heading level for semantic structure
  * @returns {JSX.Element} A dialog header with title and close button
  *
  * @example
- * ```jsx
+ * ```tsx
  * <DialogHeader
+ *   id="dialog-title-1"
  *   dialogTitle="Confirm Action"
  *   onClick={() => setIsOpen(false)}
  *   type="h2"
  * />
  * ```
  */
-
-const DialogHeader = ({
+const DialogHeader: React.FC<DialogHeaderProps> = ({
   dialogTitle,
   onClick,
+  id,
   type = "h3",
-}: DialogHeaderProps): JSX.Element => {
-  const handleClose = () => {
+}) => {
+  const handleClose = useCallback(() => {
     onClick();
-  };
+  }, [onClick]);
+
   return (
     <UI as="div" classes="dialog-header">
-      <Heading type={type} className="dialog-title">
+      <Heading type={type} className="dialog-title" id={id}>
         {dialogTitle || "Dialog"}
       </Heading>
       <Button

package/src/components/heading/heading.stories.tsx

@@ -3,22 +3,62 @@ import { within, expect } from "storybook/test";
 
 import Heading from "./heading";
 
+/**
+ * @deprecated This component is deprecated. Use Title component instead.
+ */
 const meta: Meta<typeof Heading> = {
-  title: "FP.REACT Components/Heading",
+  title: "FP.REACT Components/Heading (Deprecated)",
   component: Heading,
-  tags: ["version:1.0.0"],
+  tags: ["version:1.0.0", "deprecated"],
   parameters: {
     actions: { argTypesRegex: "^on.*" },
     docs: {
       description: {
-        component: "Heading description here...",
+        component: `
+# ⚠️ DEPRECATED: Use Title Component Instead
+
+The \`Heading\` component is **deprecated** and will be removed in **v3.0.0**.
+
+Please migrate to the new [\`Title\`](?path=/docs/fp-react-components-title--docs) component.
+
+## Migration Guide
+
+\`\`\`tsx
+// ❌ Old API (deprecated):
+import { Heading } from '@fpkit/acss';
+<Heading type="h2">Section Title</Heading>
+
+// ✅ New API:
+import { Title } from '@fpkit/acss';
+<Title level="h2">Section Title</Title>
+\`\`\`
+
+### Key Changes
+
+1. **Component Name**: \`Heading\` → \`Title\`
+2. **Prop Name**: \`type\` → \`level\`
+3. **Default Level**: Changed from \`h3\` to \`h2\` (update if you relied on the default)
+
+### Why the Change?
+
+- **Better API**: \`level\` is more semantic than \`type\`
+- **Improved Accessibility**: Enhanced WCAG 2.1 compliance
+- **Better Documentation**: Comprehensive JSDoc comments
+- **Performance**: Memoization to prevent unnecessary re-renders
+
+## Current Behavior
+
+This component still works for backwards compatibility but will log deprecation warnings in development mode.
+
+**Removal Timeline**: v3.0.0 (TBD)
+      `,
       },
     },
   },
   args: {
     children: "Default title",
   },
-} as Story;
+} satisfies Meta<typeof Heading>;
 
 export default meta;
 type Story = StoryObj<typeof Heading>;

package/src/components/heading/heading.tsx

@@ -1,27 +1,93 @@
-import React from 'react'
-import UI from '#components/ui'
-import { type } from 'os'
+import React from "react";
+import Title from "#components/title/title";
 
+/**
+ * @deprecated Use `Title` component instead. This component will be removed in v3.0.0.
+ *
+ * @remarks
+ * The `Heading` component has been deprecated in favor of the new `Title` component
+ * which offers improved API design and better accessibility features.
+ *
+ * **Migration Guide:**
+ * - Rename `Heading` → `Title`
+ * - Rename prop `type` → `level`
+ * - Default level changed from `h3` → `h2` (update if you relied on the default)
+ *
+ * @example
+ * // Before (deprecated):
+ * <Heading type="h2">Section Title</Heading>
+ *
+ * // After:
+ * <Title level="h2">Section Title</Title>
+ *
+ * @see {@link Title} for the new component
+ */
 export type TitleProps = {
-  children: React.ReactNode
-  type: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
-  ui?: string
-} & React.ComponentProps<typeof UI>
+  /**
+   * @deprecated Use `level` prop on the `Title` component instead.
+   */
+  children: React.ReactNode;
 
-const Heading = ({
-  type = 'h3',
-  id,
-  styles,
-  ui,
-  children,
-  ...props
-}: TitleProps) => {
-  return (
-    <UI as={type} id={id} styles={styles} data-ui={ui} {...props}>
-      {children}
-    </UI>
-  )
-}
+  /**
+   * @deprecated Use `level` prop on the `Title` component instead.
+   */
+  type?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
 
-export default Heading
-Heading.displayName = 'Heading'
+  /**
+   * @deprecated Use `ui` prop on the `Title` component.
+   */
+  ui?: string;
+} & Omit<React.ComponentPropsWithoutRef<typeof Title>, 'level'>;
+
+/**
+ * Heading - Deprecated component wrapper for Title.
+ *
+ * @deprecated Use {@link Title} component instead. Will be removed in v3.0.0.
+ *
+ * This component provides backwards compatibility for existing code using
+ * the old `Heading` component API. It forwards all props to the new `Title`
+ * component with appropriate prop name mapping.
+ *
+ * **Breaking Changes in v3.0.0:**
+ * - This component will be removed
+ * - Migrate to `Title` component before upgrading
+ *
+ * **Migration Steps:**
+ * 1. Replace all `<Heading>` imports with `<Title>`
+ * 2. Rename `type` prop to `level`
+ * 3. Review default behavior (default changed from h3 to h2)
+ *
+ * @example
+ * // Old API (still works but deprecated):
+ * import { Heading } from '@fpkit/acss';
+ * <Heading type="h2">Section</Heading>
+ *
+ * @example
+ * // New API (recommended):
+ * import { Title } from '@fpkit/acss';
+ * <Title level="h2">Section</Title>
+ *
+ * @param {TitleProps} props - Component props (maps old API to new)
+ * @returns {React.ReactElement} The rendered Title component
+ */
+const Heading = React.forwardRef<HTMLHeadingElement, TitleProps>(
+  ({ type = "h3", ...props }, ref) => {
+    // Development warning for deprecated usage
+    if (process.env.NODE_ENV === "development") {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[@fpkit/acss] Heading component is deprecated and will be removed in v3.0.0. ` +
+        `Please use the Title component instead.\n` +
+        `Migration: <Heading type="${type}"> → <Title level="${type}">\n` +
+        `See documentation: https://fpkit.dev/components/title`
+      );
+    }
+
+    // Map old 'type' prop to new 'level' prop
+    return <Title level={type} ref={ref} {...props} />;
+  }
+);
+
+Heading.displayName = "Heading (Deprecated)";
+
+export default Heading;