@papernote/ui 1.2.0 → 1.3.0

package/dist/styles.css

@@ -969,49 +969,6 @@ h4{
   border-color: rgb(231 229 228 / var(--tw-divide-opacity, 1));
 }
 
-.table-header{
-  --tw-bg-opacity: 1;
-  background-color: rgb(250 250 249 / var(--tw-bg-opacity, 1));
-}
-
-.table-header-cell{
-  padding-left: 1.5rem;
-  padding-right: 1.5rem;
-  padding-top: 0.75rem;
-  padding-bottom: 0.75rem;
-  text-align: left;
-  font-size: 0.75rem;
-  line-height: 1.125rem;
-  font-weight: 500;
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  --tw-text-opacity: 1;
-  color: rgb(120 113 108 / var(--tw-text-opacity, 1));
-}
-
-.table-cell{
-  white-space: nowrap;
-  padding-left: 1.5rem;
-  padding-right: 1.5rem;
-  padding-top: 1rem;
-  padding-bottom: 1rem;
-  font-size: 0.875rem;
-  line-height: 1.375rem;
-  --tw-text-opacity: 1;
-  color: rgb(68 64 60 / var(--tw-text-opacity, 1));
-}
-
-.table-row{
-  transition-property: color, background-color, border-color, text-decoration-color, fill, stroke;
-  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
-  transition-duration: 150ms;
-}
-
-.table-row:hover{
-  --tw-bg-opacity: 1;
-  background-color: rgb(250 250 249 / var(--tw-bg-opacity, 1));
-}
-
 /* Navigation Styles - Notebook-like */
 
 /* Switch Toggle Styles - Refined */
@@ -1396,6 +1353,10 @@ input:checked + .slider:before{
   top: 5rem;
 }
 
+.top-3{
+  top: 0.75rem;
+}
+
 .top-4{
   top: 1rem;
 }
@@ -1739,14 +1700,6 @@ input:checked + .slider:before{
   display: table;
 }
 
-.table-cell{
-  display: table-cell;
-}
-
-.table-row{
-  display: table-row;
-}
-
 .grid{
   display: grid;
 }
@@ -1755,6 +1708,10 @@ input:checked + .slider:before{
   display: none;
 }
 
+.aspect-square{
+  aspect-ratio: 1 / 1;
+}
+
 .h-0{
   height: 0px;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papernote/ui",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "A modern React component library with a paper notebook aesthetic - minimal, professional, and expressive",
   "main": "dist/index.js",

package/src/components/Box.stories.tsx

@@ -0,0 +1,377 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useRef, useEffect, useState } from 'react';
+import { Box } from './Box';
+import Stack from './Stack';
+import Text from './Text';
+import Button from './Button';
+
+const meta = {
+  title: 'Layout/Box',
+  component: Box,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+Box is a generic container component with design system spacing and borders.
+
+## Features
+- **Padding**: none, xs, sm, md, lg, xl (with directional variants)
+- **Margin**: none, xs, sm, md, lg, xl, auto (with directional variants)
+- **Border**: none, top, bottom, left, right, all
+- **Border color**: default, primary, accent
+- **Border radius**: none, sm, md, lg, xl, full
+- **Width/Height**: auto, full, fit, screen
+- **Ref forwarding**: Supports refs for DOM access
+
+## Usage
+
+\`\`\`tsx
+import { Box } from 'notebook-ui';
+
+// Basic container with padding
+<Box padding="md">
+  Content here
+</Box>
+
+// With border and rounded corners
+<Box padding="lg" border="all" rounded="md">
+  Card-like container
+</Box>
+
+// With ref for DOM access
+const boxRef = useRef<HTMLDivElement>(null);
+<Box ref={boxRef} padding="md">
+  Measurable content
+</Box>
+\`\`\`
+        `,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    padding: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+      description: 'Padding on all sides',
+    },
+    paddingTop: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+    },
+    paddingBottom: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+    },
+    paddingLeft: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+    },
+    paddingRight: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+    },
+    margin: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'auto'],
+      description: 'Margin on all sides',
+    },
+    marginTop: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'auto'],
+    },
+    marginBottom: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'auto'],
+    },
+    marginLeft: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'auto'],
+    },
+    marginRight: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'auto'],
+    },
+    border: {
+      control: 'select',
+      options: ['none', 'top', 'bottom', 'left', 'right', 'all'],
+      description: 'Border style',
+    },
+    borderColor: {
+      control: 'select',
+      options: ['default', 'primary', 'accent'],
+      description: 'Border color',
+    },
+    rounded: {
+      control: 'select',
+      options: ['none', 'sm', 'md', 'lg', 'xl', 'full'],
+      description: 'Border radius',
+    },
+    width: {
+      control: 'select',
+      options: [undefined, 'auto', 'full', 'fit', 'screen'],
+      description: 'Width',
+    },
+    height: {
+      control: 'select',
+      options: [undefined, 'auto', 'full', 'screen'],
+      description: 'Height',
+    },
+  },
+} satisfies Meta<typeof Box>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    padding: 'md',
+    children: 'Basic box with medium padding',
+  },
+};
+
+export const Padding: Story = {
+  render: () => (
+    <Stack spacing="md">
+      <Box padding="xs" className="bg-paper-100">
+        <Text size="sm">padding="xs"</Text>
+      </Box>
+      <Box padding="sm" className="bg-paper-100">
+        <Text size="sm">padding="sm"</Text>
+      </Box>
+      <Box padding="md" className="bg-paper-100">
+        <Text size="sm">padding="md"</Text>
+      </Box>
+      <Box padding="lg" className="bg-paper-100">
+        <Text size="sm">padding="lg"</Text>
+      </Box>
+      <Box padding="xl" className="bg-paper-100">
+        <Text size="sm">padding="xl"</Text>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const DirectionalPadding: Story = {
+  render: () => (
+    <Stack spacing="md">
+      <Box paddingTop="lg" className="bg-paper-100">
+        <Text size="sm">paddingTop="lg"</Text>
+      </Box>
+      <Box paddingBottom="lg" className="bg-paper-100">
+        <Text size="sm">paddingBottom="lg"</Text>
+      </Box>
+      <Box paddingLeft="lg" className="bg-paper-100">
+        <Text size="sm">paddingLeft="lg"</Text>
+      </Box>
+      <Box paddingRight="lg" className="bg-paper-100">
+        <Text size="sm">paddingRight="lg"</Text>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const WithBorder: Story = {
+  render: () => (
+    <Stack spacing="md">
+      <Box padding="md" border="all">
+        <Text size="sm">border="all"</Text>
+      </Box>
+      <Box padding="md" border="top">
+        <Text size="sm">border="top"</Text>
+      </Box>
+      <Box padding="md" border="bottom">
+        <Text size="sm">border="bottom"</Text>
+      </Box>
+      <Box padding="md" border="left">
+        <Text size="sm">border="left"</Text>
+      </Box>
+      <Box padding="md" border="right">
+        <Text size="sm">border="right"</Text>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const BorderColors: Story = {
+  render: () => (
+    <Stack spacing="md">
+      <Box padding="md" border="all" borderColor="default">
+        <Text size="sm">borderColor="default"</Text>
+      </Box>
+      <Box padding="md" border="all" borderColor="primary">
+        <Text size="sm">borderColor="primary"</Text>
+      </Box>
+      <Box padding="md" border="all" borderColor="accent">
+        <Text size="sm">borderColor="accent"</Text>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const Rounded: Story = {
+  render: () => (
+    <Stack spacing="md">
+      <Box padding="md" border="all" rounded="none">
+        <Text size="sm">rounded="none"</Text>
+      </Box>
+      <Box padding="md" border="all" rounded="sm">
+        <Text size="sm">rounded="sm"</Text>
+      </Box>
+      <Box padding="md" border="all" rounded="md">
+        <Text size="sm">rounded="md"</Text>
+      </Box>
+      <Box padding="md" border="all" rounded="lg">
+        <Text size="sm">rounded="lg"</Text>
+      </Box>
+      <Box padding="md" border="all" rounded="xl">
+        <Text size="sm">rounded="xl"</Text>
+      </Box>
+      <Box padding="md" border="all" rounded="full" style={{ width: '150px', textAlign: 'center' }}>
+        <Text size="sm">rounded="full"</Text>
+      </Box>
+    </Stack>
+  ),
+};
+
+export const CardLike: Story = {
+  render: () => (
+    <Box padding="lg" border="all" rounded="lg" className="bg-white shadow-sm" style={{ width: '300px' }}>
+      <Stack spacing="sm">
+        <Text as="h3" size="lg" weight="semibold">Card Title</Text>
+        <Text color="secondary">
+          This box is styled to look like a card with padding, border, and rounded corners.
+        </Text>
+        <Box marginTop="sm">
+          <Button variant="primary" size="sm">Action</Button>
+        </Box>
+      </Stack>
+    </Box>
+  ),
+};
+
+export const CenteredWithMargin: Story = {
+  render: () => (
+    <div style={{ width: '400px', border: '1px dashed #ccc' }}>
+      <Box 
+        padding="md" 
+        margin="auto" 
+        border="all" 
+        rounded="md"
+        style={{ width: 'fit-content' }}
+      >
+        <Text>Centered with margin="auto"</Text>
+      </Box>
+    </div>
+  ),
+};
+
+/**
+ * Box supports ref forwarding, allowing you to access the underlying DOM element.
+ * This is useful for measuring dimensions, handling scroll, or integrating with
+ * third-party libraries that need DOM access.
+ */
+export const WithRef: Story = {
+  render: function RefExample() {
+    const boxRef = useRef<HTMLDivElement>(null);
+    const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+
+    useEffect(() => {
+      if (boxRef.current) {
+        const { offsetWidth, offsetHeight } = boxRef.current;
+        setDimensions({ width: offsetWidth, height: offsetHeight });
+      }
+    }, []);
+
+    return (
+      <Stack spacing="md">
+        <Box 
+          ref={boxRef} 
+          padding="lg" 
+          border="all" 
+          rounded="md"
+          className="bg-paper-50"
+        >
+          <Text>This box's dimensions are measured using a ref</Text>
+        </Box>
+        <Box padding="sm" border="all" rounded="sm" className="bg-success-50">
+          <Text size="sm" color="success">
+            Measured: {dimensions.width}px x {dimensions.height}px
+          </Text>
+        </Box>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * Another ref example showing focus management.
+ */
+export const RefForFocus: Story = {
+  render: function FocusExample() {
+    const boxRef = useRef<HTMLDivElement>(null);
+    const [isFocused, setIsFocused] = useState(false);
+
+    const handleFocus = () => {
+      if (boxRef.current) {
+        boxRef.current.focus();
+        setIsFocused(true);
+      }
+    };
+
+    return (
+      <Stack spacing="md">
+        <Box 
+          ref={boxRef}
+          tabIndex={0}
+          padding="lg" 
+          border="all" 
+          borderColor={isFocused ? 'accent' : 'default'}
+          rounded="md"
+          onFocus={() => setIsFocused(true)}
+          onBlur={() => setIsFocused(false)}
+          className="transition-colors outline-none focus:ring-2 focus:ring-accent-400"
+        >
+          <Text>Click the button or press Tab to focus this box</Text>
+        </Box>
+        <Button variant="secondary" onClick={handleFocus}>
+          Focus the Box
+        </Button>
+        <Text size="sm" color="muted">
+          Status: {isFocused ? 'Focused' : 'Not focused'}
+        </Text>
+      </Stack>
+    );
+  },
+};
+
+export const NestedBoxes: Story = {
+  render: () => (
+    <Box padding="lg" border="all" rounded="lg" className="bg-paper-50">
+      <Text weight="semibold" size="lg">Outer Box</Text>
+      <Box padding="md" marginTop="md" border="all" rounded="md" className="bg-white">
+        <Text>Inner Box 1</Text>
+      </Box>
+      <Box padding="md" marginTop="md" border="all" rounded="md" className="bg-white">
+        <Text>Inner Box 2</Text>
+      </Box>
+    </Box>
+  ),
+};
+
+export const WidthOptions: Story = {
+  render: () => (
+    <Stack spacing="md" style={{ width: '400px' }}>
+      <Box padding="sm" border="all" width="auto">
+        <Text size="sm">width="auto" (shrinks to content)</Text>
+      </Box>
+      <Box padding="sm" border="all" width="full">
+        <Text size="sm">width="full" (100% of parent)</Text>
+      </Box>
+      <Box padding="sm" border="all" width="fit">
+        <Text size="sm">width="fit"</Text>
+      </Box>
+    </Stack>
+  ),
+};

package/src/components/Box.tsx

@@ -1,7 +1,7 @@
 // Box Component - Generic container with design system styling
 // Provides consistent padding, borders, and other container styles
 
-import React from 'react';
+import React, { forwardRef } from 'react';
 
 export interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Content */
@@ -42,8 +42,9 @@ export interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
 
 /**
  * Box component for generic containers with design system spacing and borders.
+ * Supports ref forwarding for DOM access.
  */
-export const Box: React.FC<BoxProps> = ({
+export const Box = forwardRef<HTMLDivElement, BoxProps>(({
   children,
   padding,
   paddingTop,
@@ -62,7 +63,7 @@ export const Box: React.FC<BoxProps> = ({
   height,
   className = '',
   ...htmlProps
-}) => {
+}, ref) => {
   const spacingMap = {
     none: '0',
     xs: '2',
@@ -148,6 +149,7 @@ export const Box: React.FC<BoxProps> = ({
 
   return (
     <div
+      ref={ref}
       {...htmlProps}
       className={`
         ${getPaddingClass()}
@@ -163,6 +165,8 @@ export const Box: React.FC<BoxProps> = ({
       {children}
     </div>
   );
-};
+});
+
+Box.displayName = 'Box';
 
 export default Box;

package/src/components/Button.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { forwardRef } from 'react';
 import { Loader2 } from 'lucide-react';
 
 /**
@@ -31,6 +31,8 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
  * A versatile button component that supports multiple visual styles, sizes, icons,
  * loading states, and notification badges.
  *
+ * Supports ref forwarding for DOM access.
+ *
  * @example Basic usage
  * ```tsx
  * <Button variant="primary">Click me</Button>
@@ -38,9 +40,9 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
  *
  * @example With icon and loading
  * ```tsx
- * <Button 
- *   variant="secondary" 
- *   icon={<Save />} 
+ * <Button
+ *   variant="secondary"
+ *   icon={<Save />}
  *   loading={isSaving}
  * >
  *   Save Changes
@@ -49,16 +51,22 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
  *
  * @example Icon-only with badge
  * ```tsx
- * <Button 
- *   iconOnly 
- *   badge={5} 
+ * <Button
+ *   iconOnly
+ *   badge={5}
  *   badgeVariant="error"
  * >
  *   <Bell />
  * </Button>
  * ```
+ *
+ * @example With ref
+ * ```tsx
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * <Button ref={buttonRef}>Focusable</Button>
+ * ```
  */
-export default function Button({
+const Button = forwardRef<HTMLButtonElement, ButtonProps>(({
   variant = 'primary',
   size = 'md',
   loading = false,
@@ -72,7 +80,7 @@ export default function Button({
   disabled,
   className = '',
   ...props
-}: ButtonProps) {
+}, ref) => {
   const baseStyles = 'inline-flex items-center justify-center font-medium rounded-lg border transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-accent-400 disabled:opacity-40 disabled:cursor-not-allowed';
 
   const variantStyles = {
@@ -111,6 +119,7 @@ export default function Button({
 
   const buttonElement = (
     <button
+      ref={ref}
       className={`
         ${baseStyles}
         ${variantStyles[variant]}
@@ -163,4 +172,8 @@ export default function Button({
       </span>
     </div>
   );
-}
+});
+
+Button.displayName = 'Button';
+
+export default Button;

package/src/components/Card.tsx

@@ -1,10 +1,10 @@
-import React from 'react';
+import React, { forwardRef } from 'react';
 import { Skeleton } from './Loading';
 
 /**
  * Card component props
  */
-export interface CardProps {
+export interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onClick'> {
   /** Card content */
   children: React.ReactNode;
   /** Visual style variant affecting padding and shadow */
@@ -24,6 +24,8 @@ export interface CardProps {
 /**
  * Card - Container component with paper aesthetic and subtle shadow
  *
+ * Supports ref forwarding for DOM access.
+ *
  * A content container with paper texture, border, and shadow effects. Supports
  * different sizes, variants (padding/shadow levels), and loading states.
  *
@@ -53,8 +55,14 @@ export interface CardProps {
  *   <p>Content</p>
  * </Card>
  * ```
+ * 
+ * @example With ref
+ * ```tsx
+ * const cardRef = useRef<HTMLDivElement>(null);
+ * <Card ref={cardRef}>Content</Card>
+ * ```
  */
-export default function Card({
+const Card = forwardRef<HTMLDivElement, CardProps>(({
   children,
   variant = 'default',
   width = 'auto',
@@ -62,7 +70,8 @@ export default function Card({
   onClick,
   hoverable = false,
   loading = false,
-}: CardProps) {
+  ...htmlProps
+}, ref) => {
   const baseStyles = 'bg-white bg-subtle-grain border-2 border-paper-300 transition-shadow duration-200';
 
   const variantStyles = {
@@ -84,6 +93,8 @@ export default function Card({
 
   return (
     <div
+      ref={ref}
+      {...htmlProps}
       className={`${baseStyles} ${variantStyles[variant]} ${widthStyles[width]} ${interactiveStyles} ${className}`}
       onClick={!loading ? onClick : undefined}
       role={onClick ? 'button' : undefined}
@@ -101,7 +112,11 @@ export default function Card({
       )}
     </div>
   );
-}
+});
+
+Card.displayName = 'Card';
+
+export default Card;
 
 /**
  * CardHeader component props