@fpkit/acss 6.4.2 → 6.5.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fpkit/acss",
   "description": "A lightweight React UI library for building modern and accessible components that leverage CSS custom properties for reactive Styles.",
   "private": false,
-  "version": "6.4.2",
+  "version": "6.5.0",
   "engines": {
     "node": ">=22.12.0",
     "npm": ">=8.0.0"
@@ -123,5 +123,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "e0e6e8a0bd3931cd33bfcabcab7f25f276bfe0bf"
+  "gitHead": "9063512fa822963d8151c972bed9f5b0e531df0f"
 }

package/src/components/dialog/README.mdx

@@ -15,6 +15,8 @@ A modern, accessible dialog component system built with React and TypeScript, le
 ✅ **Two Modes** - Modal dialogs (overlay) and inline alert dialogs
 ✅ **Focus Management** - Automatic focus restoration to trigger element
 ✅ **Flexible API** - Controlled `Dialog` or uncontrolled `DialogModal` wrapper
+✅ **Size Variants** - Small, medium, large, and full-screen dialog sizes
+✅ **Position Control** - Center, top, bottom, left/right drawers, and corner positioning
 ✅ **Customizable** - CSS custom properties for theming
 ✅ **Keyboard Accessible** - `:focus-visible` styles, Escape key support
 ✅ **High Contrast Mode** - Supports `prefers-contrast: high` media query
@@ -116,6 +118,8 @@ function MyComponent() {
 | `className` | `string` | `""` | Additional CSS classes to apply to the dialog |
 | `dialogLabel` | `string` | - | Optional `aria-label` for the dialog |
 | `styles` | `CSSProperties` | - | Inline styles to apply to the dialog element |
+| `size` | `"sm" \| "md" \| "lg" \| "full"` | - | Size variant controlling dialog dimensions |
+| `position` | `"center" \| "top" \| "bottom" \| "left" \| "right" \| "top-left" \| "top-right" \| "bottom-left" \| "bottom-right"` | `"center"` | Position of the dialog on screen |
 
 ---
 
@@ -251,6 +255,70 @@ function SimpleExample() {
 }
 ```
 
+### Size Variants
+
+```tsx
+import { DialogModal } from "@fpkit/acss";
+
+function SizeExample() {
+  return (
+    <>
+      {/* Small dialog (25rem) */}
+      <DialogModal dialogTitle="Small" btnLabel="Open Small" size="sm">
+        <p>A compact dialog for simple actions.</p>
+      </DialogModal>
+
+      {/* Medium dialog (32rem) */}
+      <DialogModal dialogTitle="Medium" btnLabel="Open Medium" size="md">
+        <p>A standard dialog for forms and content.</p>
+      </DialogModal>
+
+      {/* Large dialog (48rem) */}
+      <DialogModal dialogTitle="Large" btnLabel="Open Large" size="lg">
+        <p>A wide dialog for complex content.</p>
+      </DialogModal>
+
+      {/* Full-screen dialog */}
+      <DialogModal dialogTitle="Full Screen" btnLabel="Open Full" size="full">
+        <p>This dialog fills the entire viewport.</p>
+      </DialogModal>
+    </>
+  );
+}
+```
+
+### Position Variants
+
+```tsx
+import { DialogModal } from "@fpkit/acss";
+
+function PositionExample() {
+  return (
+    <>
+      {/* Top-positioned dialog */}
+      <DialogModal dialogTitle="Top" btnLabel="Open Top" position="top">
+        <p>Positioned at the top center of the viewport.</p>
+      </DialogModal>
+
+      {/* Bottom sheet */}
+      <DialogModal dialogTitle="Bottom Sheet" btnLabel="Open Bottom" position="bottom">
+        <p>Positioned at the bottom, like a mobile bottom sheet.</p>
+      </DialogModal>
+
+      {/* Right drawer (full-height side panel) */}
+      <DialogModal dialogTitle="Right Drawer" btnLabel="Open Drawer" size="sm" position="right">
+        <p>A full-height drawer sliding in from the right.</p>
+      </DialogModal>
+
+      {/* Corner positioning */}
+      <DialogModal dialogTitle="Corner" btnLabel="Open Corner" size="sm" position="bottom-right">
+        <p>Positioned in the bottom-right corner.</p>
+      </DialogModal>
+    </>
+  );
+}
+```
+
 ### Custom Styling
 
 ```tsx
@@ -370,7 +438,13 @@ Override these variables to customize the dialog appearance:
 ```css
 :root {
   /* Dimensions */
-  --dialog-min-w: max(20rem, 80%);
+  --dialog-min-width: max(20rem, 80%);
+  --dialog-width: var(--dialog-min-width);
+  --dialog-max-width: 90vw;
+  --dialog-height: auto;
+  --dialog-max-height: 85vh;
+  --dialog-margin: auto;
+  --dialog-inset: 0;
   --dialog-gap: 0.625rem;
   --dialog-padding: 1.5rem;
   --dialog-padding-inline: 1rem;
@@ -421,6 +495,8 @@ import type {
   DialogModalProps,
   DialogHeaderProps,
   DialogFooterProps,
+  DialogSize,
+  DialogPosition,
 } from "@fpkit/acss";
 ```
 
@@ -429,6 +505,13 @@ import type {
 All components are fully typed with comprehensive JSDoc comments:
 
 ```tsx
+type DialogSize = "sm" | "md" | "lg" | "full";
+type DialogPosition =
+  | "center" | "top" | "bottom"
+  | "left" | "right"
+  | "top-left" | "top-right"
+  | "bottom-left" | "bottom-right";
+
 interface DialogProps extends BaseDialogProps {
   isOpen: boolean;
   onOpenChange: (open: boolean) => void;
@@ -438,6 +521,8 @@ interface DialogProps extends BaseDialogProps {
   confirmLabel?: string;
   cancelLabel?: string;
   hideFooter?: boolean;
+  size?: DialogSize;
+  position?: DialogPosition;
 }
 ```
 
@@ -554,7 +639,7 @@ For older browsers, consider using a polyfill like [`dialog-polyfill`](https://g
 ## Testing
 
 The dialog component has comprehensive test coverage:
-- ✓ 24 tests covering all scenarios
+- ✓ 40 tests covering all scenarios
 - ✓ Controlled vs uncontrolled behavior
 - ✓ Modal vs non-modal rendering
 - ✓ ARIA attributes validation

package/src/components/dialog/STYLES.mdx

@@ -18,6 +18,8 @@ accessibility and high contrast mode support.
 
 - **Native `<dialog>` element** - Built on HTML5 dialog with proper semantics
 - **Flexible layout** - Flexbox-based column layout with customizable gap
+- **Size variants** - Small, medium, large, and full-screen via `data-size` attribute
+- **Position variants** - Center, top, bottom, left/right drawers, and corners via `data-position` attribute
 - **Header with close button** - Pre-styled header section with close control
 - **Action footer** - Flexible footer for action buttons
 - **Keyboard accessibility** - Full keyboard navigation with visible focus
@@ -38,6 +40,12 @@ Root-level variables define the dialog's overall appearance:
 :root {
   /* Dimensions */
   --dialog-min-width: max(20rem, 80%); /* Responsive width: min 320px or 80% */
+  --dialog-width: var(--dialog-min-width); /* Actual applied width */
+  --dialog-max-width: 90vw; /* Maximum width cap */
+  --dialog-height: auto; /* Dialog height */
+  --dialog-max-height: 85vh; /* Maximum height cap */
+  --dialog-margin: auto; /* Positioning margin */
+  --dialog-inset: 0; /* Positioning inset */
 
   /* Layout */
   --dialog-display: flex;
@@ -739,7 +747,8 @@ All dialog CSS variables follow specific patterns:
 
 | Category       | Variable Pattern             | Example                                          |
 | -------------- | ---------------------------- | ------------------------------------------------ |
-| **Dimensions** | `--dialog-{dimension}`       | `--dialog-min-width`                             |
+| **Dimensions** | `--dialog-{dimension}`       | `--dialog-width`, `--dialog-max-width`, `--dialog-height` |
+| **Position**   | `--dialog-{position-prop}`   | `--dialog-margin`, `--dialog-inset`              |
 | **Layout**     | `--dialog-{layout-property}` | `--dialog-display`, `--dialog-flex-direction`    |
 | **Spacing**    | `--dialog-{spacing-type}`    | `--dialog-padding`, `--dialog-gap`               |
 | **Borders**    | `--dialog-border-{property}` | `--dialog-border-color`, `--dialog-border-width` |
@@ -752,6 +761,12 @@ All dialog CSS variables follow specific patterns:
 ```css
 /* Dimensions */
 --dialog-min-width          /* Minimum width (responsive) */
+--dialog-width              /* Applied width (defaults to min-width) */
+--dialog-max-width          /* Maximum width cap (90vw) */
+--dialog-height             /* Dialog height (auto) */
+--dialog-max-height         /* Maximum height cap (85vh) */
+--dialog-margin             /* Positioning margin (auto) */
+--dialog-inset              /* Positioning inset (0) */
 
 /* Layout */
 --dialog-display            /* Display mode (flex) */
@@ -815,29 +830,121 @@ For browsers without native `<dialog>` support, use:
 </script>
 ```
 
-## Performance Tips
+## Size Variants
+
+Control dialog dimensions using the `size` prop (React) or `data-size` attribute (HTML).
+Sizes are applied via `data-size` attribute selectors in CSS.
 
-### Avoid Inline Styles
+| Size | Width | Description |
+|------|-------|-------------|
+| `sm` | 25rem (400px) | Compact dialog for simple confirmations |
+| `md` | 32rem (512px) | Standard dialog for forms |
+| `lg` | 48rem (768px) | Wide dialog for complex content |
+| `full` | 100vw/100vh | Full-screen dialog filling the viewport |
 
-Create reusable dialog variants:
+### CSS for Size Variants
 
 ```css
-.dialog-sm {
-  --dialog-min-width: max(15rem, 50%);
-  --dialog-padding: 1rem;
+dialog[data-size="sm"] { --dialog-width: 25rem; }
+dialog[data-size="md"] { --dialog-width: 32rem; }
+dialog[data-size="lg"] { --dialog-width: 48rem; }
+
+/* Full-screen uses direct values to override browser UA stylesheet */
+dialog[data-size="full"] {
+  box-sizing: border-box;
+  width: 100vw;
+  max-width: 100vw;
+  height: 100vh;
+  max-height: 100vh;
+  margin: 0;
+  inset: 0;
+  border: 0;
+  border-radius: 0;
 }
+```
 
-.dialog-lg {
-  --dialog-min-width: max(40rem, 90%);
-  --dialog-padding: 2rem;
+### React Usage
+
+```tsx
+<Dialog size="sm" ... />
+<DialogModal size="lg" btnLabel="Open Large" ... />
+```
+
+### HTML Usage
+
+```html
+<dialog data-size="sm">Small dialog</dialog>
+<dialog data-size="full">Full-screen dialog</dialog>
+```
+
+## Position Variants
+
+Control dialog placement using the `position` prop (React) or `data-position` attribute (HTML).
+Left/right positions create full-height drawer panels.
+
+| Position | Behavior |
+|----------|----------|
+| `center` | Centered on screen (default) |
+| `top` | Anchored to top center |
+| `bottom` | Anchored to bottom center (bottom sheet) |
+| `left` | Full-height left drawer |
+| `right` | Full-height right drawer |
+| `top-left` | Anchored to top-left corner |
+| `top-right` | Anchored to top-right corner |
+| `bottom-left` | Anchored to bottom-left corner |
+| `bottom-right` | Anchored to bottom-right corner |
+
+### CSS for Position Variants
+
+Position variants override `--dialog-margin` and `--dialog-inset` to control placement:
+
+```css
+dialog[data-position="top"] {
+  --dialog-margin: 0 auto auto auto;
+  --dialog-inset: 0;
+}
+
+dialog[data-position="right"] {
+  --dialog-margin: 0 0 0 auto;
+  --dialog-inset: 0;
+  --dialog-height: 100vh;
+  --dialog-max-height: 100vh;
+  --dialog-border-radius: 0;
 }
 ```
 
+### React Usage
+
+```tsx
+<Dialog position="top" ... />
+<DialogModal size="sm" position="right" btnLabel="Open Drawer" ... />
+```
+
+### HTML Usage
+
 ```html
-<dialog class="dialog-sm">Small dialog</dialog>
-<dialog class="dialog-lg">Large dialog</dialog>
+<dialog data-position="bottom">Bottom sheet</dialog>
+<dialog data-size="sm" data-position="right">Right drawer</dialog>
 ```
 
+### Combining Size and Position
+
+Size and position can be combined for precise control:
+
+```tsx
+{/* Right drawer panel */}
+<DialogModal size="sm" position="right" dialogTitle="Settings" btnLabel="Open">
+  <p>Drawer content</p>
+</DialogModal>
+
+{/* Small bottom-right notification */}
+<DialogModal size="sm" position="bottom-right" dialogTitle="Notice" btnLabel="Show">
+  <p>Corner notification</p>
+</DialogModal>
+```
+
+## Performance Tips
+
 ### Use Native Dialog Methods
 
 Prefer `.showModal()` over custom implementations:

package/src/components/dialog/dialog-modal.stories.tsx

@@ -38,6 +38,18 @@ const meta: Meta<typeof DialogModal> = {
     isOpen: false,
     onClose: () => {},
   },
+  argTypes: {
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg", "full"],
+      description: "Size variant controlling dialog dimensions",
+    },
+    position: {
+      control: "select",
+      options: ["center", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"],
+      description: "Position of the dialog on screen",
+    },
+  },
 } as Meta;
 
 export default meta;
@@ -49,9 +61,14 @@ export const Default: Story = {
       "DialogModal is a modal dialog component that provides an accessible overlay for displaying content.",
   },
   decorators: [WithInstructions()],
-  play: async ({ canvasElement }) => {
+  play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByRole("dialog")).toBeInTheDocument();
+
+    await step("Dialog renders with default center position", async () => {
+      const dialog = canvas.getByRole("dialog");
+      expect(dialog).toBeInTheDocument();
+      expect(dialog).toHaveAttribute("data-position", "center");
+    });
   },
 } as Story;
 
@@ -181,3 +198,91 @@ export const IconTriggerWithOutlineVariant: Story = {
     });
   },
 } as Story;
+
+/* ── Size variant stories ──────────────────── */
+
+export const SmallDialog: Story = {
+  args: {
+    dialogTitle: "Small Dialog",
+    btnLabel: "Open Small",
+    size: "sm",
+    children: "This is a small (25rem) dialog.",
+  },
+} as Story;
+
+export const MediumDialog: Story = {
+  args: {
+    dialogTitle: "Medium Dialog",
+    btnLabel: "Open Medium",
+    size: "md",
+    children: "This is a medium (32rem) dialog for forms and standard content.",
+  },
+} as Story;
+
+export const LargeDialog: Story = {
+  args: {
+    dialogTitle: "Large Dialog",
+    btnLabel: "Open Large",
+    size: "lg",
+    children: "This is a large (48rem) dialog with more room for complex content.",
+  },
+} as Story;
+
+export const FullScreenDialog: Story = {
+  args: {
+    dialogTitle: "Full Screen Dialog",
+    btnLabel: "Open Full Screen",
+    size: "full",
+    children: "This dialog takes up the entire viewport.",
+  },
+} as Story;
+
+/* ── Position variant stories ──────────────── */
+
+export const TopPositioned: Story = {
+  args: {
+    dialogTitle: "Top Dialog",
+    btnLabel: "Open Top",
+    position: "top",
+    children: "This dialog is positioned at the top center of the viewport.",
+  },
+} as Story;
+
+export const BottomSheet: Story = {
+  args: {
+    dialogTitle: "Bottom Sheet",
+    btnLabel: "Open Bottom Sheet",
+    position: "bottom",
+    children: "This dialog is positioned at the bottom, like a mobile bottom sheet.",
+  },
+} as Story;
+
+export const RightDrawer: Story = {
+  args: {
+    dialogTitle: "Right Drawer",
+    btnLabel: "Open Right Drawer",
+    size: "sm",
+    position: "right",
+    children: "This dialog slides in from the right as a full-height drawer panel.",
+  },
+} as Story;
+
+export const LeftDrawer: Story = {
+  args: {
+    dialogTitle: "Left Drawer",
+    btnLabel: "Open Left Drawer",
+    size: "sm",
+    position: "left",
+    children: "This dialog slides in from the left as a full-height drawer panel.",
+  },
+} as Story;
+
+export const BottomRightPositioned: Story = {
+  args: {
+    dialogTitle: "Bottom Right",
+    btnLabel: "Open Bottom Right",
+    size: "sm",
+    position: "bottom-right",
+    children: "This dialog appears in the bottom-right corner.",
+  },
+} as Story;

package/src/components/dialog/dialog-modal.tsx

@@ -81,6 +81,9 @@ export const DialogModal: React.FC<DialogModalProps> = ({
   hideFooter = false,
   btnProps,
   icon,
+  size,
+  position,
+  closeIconSize,
 }) => {
   const [isOpen, setIsOpen] = useState(false);
   const lastFocusedElement = useRef<HTMLElement | null>(null);
@@ -150,6 +153,9 @@ export const DialogModal: React.FC<DialogModalProps> = ({
         confirmLabel={confirmLabel}
         cancelLabel={cancelLabel}
         hideFooter={hideFooter}
+        size={size}
+        position={position}
+        closeIconSize={closeIconSize}
       >
         {children}
       </Dialog>

package/src/components/dialog/dialog.scss

@@ -1,5 +1,10 @@
 :root {
   --dialog-min-width: max(20rem, 80%);
+  --dialog-width: var(--dialog-min-width);
+  --dialog-max-width: 90vw;
+  --dialog-max-height: 85vh;
+  --dialog-margin: auto;
+  --dialog-inset: 0;
   --dialog-gap: 0.625rem;
   --dialog-border-color: var(--color-border);
   --dialog-border-width: thin;
@@ -33,8 +38,11 @@
 }
 
 dialog {
-  width: var(--dialog-min-width);
-  min-width: var(--dialog-min-width);
+  margin: var(--dialog-margin);
+  inset: var(--dialog-inset);
+  width: var(--dialog-width);
+  max-width: var(--dialog-max-width);
+  max-height: var(--dialog-max-height);
   gap: var(--dialog-gap);
   border: var(--dialog-border-color) var(--dialog-border-width) solid;
   border-radius: var(--dialog-border-radius);
@@ -125,3 +133,82 @@ dialog {
     outline: none;
   }
 }
+
+/* ── Size variants ─────────────────────────── */
+
+dialog[data-size="sm"] {
+  --dialog-width: 25rem;
+}
+
+dialog[data-size="md"] {
+  --dialog-width: 32rem;
+}
+
+dialog[data-size="lg"] {
+  --dialog-width: 48rem;
+}
+
+dialog[data-size="full"] {
+  box-sizing: border-box;
+  width: 100vw;
+  max-width: 100vw;
+  height: 100vh;
+  max-height: 100vh;
+  margin: 0;
+  inset: 0;
+  border: 0;
+  border-radius: 0;
+}
+
+/* ── Position variants ─────────────────────── */
+
+dialog[data-position="center"] {
+  --dialog-margin: auto;
+  --dialog-inset: 0;
+}
+
+dialog[data-position="top"] {
+  --dialog-margin: 0 auto auto auto;
+  --dialog-inset: 0;
+}
+
+dialog[data-position="bottom"] {
+  --dialog-margin: auto auto 0 auto;
+  --dialog-inset: 0;
+}
+
+dialog[data-position="left"] {
+  --dialog-margin: 0 auto 0 0;
+  --dialog-inset: 0;
+  height: 100vh;
+  max-height: 100vh;
+  border-radius: 0;
+}
+
+dialog[data-position="right"] {
+  --dialog-margin: 0 0 0 auto;
+  --dialog-inset: 0;
+  height: 100vh;
+  max-height: 100vh;
+  border-radius: 0;
+}
+
+dialog[data-position="top-left"] {
+  --dialog-margin: 0 auto auto 0;
+  --dialog-inset: 0;
+}
+
+dialog[data-position="top-right"] {
+  --dialog-margin: 0 0 auto auto;
+  --dialog-inset: 0;
+}
+
+dialog[data-position="bottom-left"] {
+  --dialog-margin: auto auto 0 0;
+  --dialog-inset: 0;
+}
+
+dialog[data-position="bottom-right"] {
+  --dialog-margin: auto 0 0 auto;
+  --dialog-inset: 0;
+}

package/src/components/dialog/dialog.stories.tsx

@@ -41,6 +41,18 @@ const meta: Meta<typeof Dialog> = {
   args: {
     children: content,
   },
+  argTypes: {
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg", "full"],
+      description: "Size variant controlling dialog dimensions",
+    },
+    position: {
+      control: "select",
+      options: ["center", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"],
+      description: "Position of the dialog on screen (defaults to center)",
+    },
+  },
   decorators: [
     (Story) => {
       return (
@@ -71,6 +83,15 @@ export const BasicDialog: Story = {
     onOpenChange: () => {},
     dialogTitle: "Basic Dialog",
   },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Dialog defaults to center position", async () => {
+      const dialog = canvas.getByRole("dialog");
+      await expect(dialog).toBeInTheDocument();
+      await expect(dialog).toHaveAttribute("data-position", "center");
+    });
+  },
 } as Story;
 
 /**
@@ -84,9 +105,14 @@ export const NonModalDialog: Story = {
     isAlertDialog: true,
     dialogTitle: "Non Modal Dialog",
   },
-  play: async ({ canvasElement }) => {
+  play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    await expect(canvas.getByRole("alertdialog")).toBeInTheDocument();
+
+    await step("Alert dialog renders with default center position", async () => {
+      const dialog = canvas.getByRole("alertdialog");
+      await expect(dialog).toBeInTheDocument();
+      await expect(dialog).toHaveAttribute("data-position", "center");
+    });
   },
 } as Story;
 
@@ -106,8 +132,9 @@ export const DialogInteractions: Story = {
     const dialog = canvas.getByRole("dialog");
     const closeButton = canvas.getByRole("button", { name: /close dialog/i });
 
-    await step("Modal is rendered", async () => {
+    await step("Modal is rendered with default center position", async () => {
       await expect(dialog).toBeInTheDocument();
+      await expect(dialog).toHaveAttribute("data-position", "center");
       await expect(closeButton).toBeInTheDocument();
     });