@papernote/ui 1.10.17 → 1.10.19

package/src/components/SkipLink.stories.tsx

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import SkipLink from './SkipLink';
+import Stack from './Stack';
+import Text from './Text';
+import Card from './Card';
+
+const meta: Meta<typeof SkipLink> = {
+  title: 'Accessibility/SkipLink',
+  component: SkipLink,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A skip link allows keyboard users to bypass repetitive navigation and jump directly to the main content. The link is visually hidden until focused (press Tab to see it).',
+      },
+    },
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof SkipLink>;
+
+export const Default: Story = {
+  args: {
+    targetId: 'main-content',
+  },
+  render: (args) => (
+    <Stack gap="lg">
+      <Text size="sm" className="text-ink-500">
+        Press Tab to reveal the skip link
+      </Text>
+      <SkipLink {...args} />
+      <Card>
+        <Stack gap="md">
+          <Text weight="bold">Fake Navigation</Text>
+          <nav>
+            <Stack direction="horizontal" gap="md">
+              <a href="#" className="text-accent-600">Home</a>
+              <a href="#" className="text-accent-600">About</a>
+              <a href="#" className="text-accent-600">Contact</a>
+            </Stack>
+          </nav>
+        </Stack>
+      </Card>
+      <Card id="main-content" tabIndex={-1}>
+        <Stack gap="md">
+          <Text weight="bold">Main Content</Text>
+          <Text>This is the main content area. The skip link will focus here when activated.</Text>
+        </Stack>
+      </Card>
+    </Stack>
+  ),
+};
+
+export const CustomText: Story = {
+  args: {
+    targetId: 'content',
+    children: 'Skip navigation',
+  },
+  render: (args) => (
+    <Stack gap="lg">
+      <Text size="sm" className="text-ink-500">
+        Press Tab to reveal the skip link with custom text
+      </Text>
+      <SkipLink {...args} />
+      <Card id="content" tabIndex={-1}>
+        <Text>Target content area</Text>
+      </Card>
+    </Stack>
+  ),
+};
+
+export const MultipleSkipLinks: Story = {
+  render: () => (
+    <Stack gap="lg">
+      <Text size="sm" className="text-ink-500">
+        Press Tab multiple times to see multiple skip links
+      </Text>
+      <SkipLink targetId="main">Skip to main content</SkipLink>
+      <SkipLink targetId="search">Skip to search</SkipLink>
+      <SkipLink targetId="footer">Skip to footer</SkipLink>
+      <Card>
+        <Text weight="bold">Navigation</Text>
+      </Card>
+      <Card id="search" tabIndex={-1}>
+        <Text weight="bold">Search Section</Text>
+      </Card>
+      <Card id="main" tabIndex={-1}>
+        <Text weight="bold">Main Content</Text>
+      </Card>
+      <Card id="footer" tabIndex={-1}>
+        <Text weight="bold">Footer</Text>
+      </Card>
+    </Stack>
+  ),
+};

package/src/components/SkipLink.tsx

@@ -0,0 +1,88 @@
+import React from 'react';
+
+/**
+ * SkipLink component props
+ */
+export interface SkipLinkProps {
+  /** The target element ID to skip to (without the # prefix) */
+  targetId: string;
+  /** Custom link text (default: "Skip to main content") */
+  children?: React.ReactNode;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * SkipLink - Accessibility skip link for keyboard navigation
+ *
+ * A skip link allows keyboard users to bypass repetitive navigation
+ * and jump directly to the main content. The link is visually hidden
+ * until focused, making it invisible to mouse users while remaining
+ * accessible to keyboard and screen reader users.
+ *
+ * Place this component at the very beginning of your page layout,
+ * before any navigation elements.
+ *
+ * @example Basic usage
+ * ```tsx
+ * // In your layout component:
+ * <SkipLink targetId="main-content" />
+ * <Navigation />
+ * <main id="main-content">
+ *   {children}
+ * </main>
+ * ```
+ *
+ * @example Custom text
+ * ```tsx
+ * <SkipLink targetId="content">Skip navigation</SkipLink>
+ * ```
+ *
+ * @example Multiple skip links
+ * ```tsx
+ * <div>
+ *   <SkipLink targetId="main-content">Skip to main content</SkipLink>
+ *   <SkipLink targetId="search">Skip to search</SkipLink>
+ * </div>
+ * ```
+ */
+export default function SkipLink({
+  targetId,
+  children = 'Skip to main content',
+  className = '',
+}: SkipLinkProps) {
+  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+    e.preventDefault();
+    const target = document.getElementById(targetId);
+    if (target) {
+      // Set tabindex to make the element focusable if it isn't already
+      if (!target.hasAttribute('tabindex')) {
+        target.setAttribute('tabindex', '-1');
+      }
+      target.focus();
+      // Scroll the element into view
+      target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+  };
+
+  return (
+    <a
+      href={`#${targetId}`}
+      onClick={handleClick}
+      className={`
+        sr-only focus:not-sr-only
+        focus:absolute focus:z-50
+        focus:top-4 focus:left-4
+        focus:px-4 focus:py-2
+        focus:bg-accent-600 focus:text-white
+        focus:rounded-lg focus:shadow-lg
+        focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-accent-400
+        font-medium text-sm
+        transition-none
+        ${className}
+      `}
+    >
+      {children}
+    </a>
+  );
+}

package/src/components/Tabs.stories.tsx

@@ -923,3 +923,129 @@ This example places the tabs in a header row separate from the content area.
     },
   },
 };
+
+/**
+ * Demonstrates custom data attributes for E2E testing and product tours.
+ * Each tab includes data-testid and data-tour attributes for reliable element targeting.
+ *
+ * Inspect the elements to see the data attributes:
+ * - `data-testid`: For E2E testing with Playwright/Cypress
+ * - `data-tour`: For product tours with Driver.js or similar libraries
+ */
+export const WithDataAttributes: Story = {
+  render: () => {
+    const [activeTab, setActiveTab] = useState('profile');
+    const tabs: Tab[] = [
+      {
+        id: 'profile',
+        label: 'Profile',
+        icon: <User className="h-4 w-4" />,
+        content: <div style={{ padding: '1rem' }}><h3>Profile</h3><p>Manage your profile information.</p></div>,
+        dataAttributes: {
+          'data-tour': 'tab-profile',
+          'data-testid': 'tab-profile',
+        },
+      },
+      {
+        id: 'settings',
+        label: 'Settings',
+        icon: <Settings className="h-4 w-4" />,
+        content: <div style={{ padding: '1rem' }}><h3>Settings</h3><p>Configure your preferences.</p></div>,
+        dataAttributes: {
+          'data-tour': 'tab-settings',
+          'data-testid': 'tab-settings',
+        },
+      },
+      {
+        id: 'notifications',
+        label: 'Notifications',
+        icon: <Bell className="h-4 w-4" />,
+        badge: 5,
+        content: <div style={{ padding: '1rem' }}><h3>Notifications</h3><p>View your notifications.</p></div>,
+        dataAttributes: {
+          'data-tour': 'tab-notifications',
+          'data-testid': 'tab-notifications',
+        },
+      },
+    ];
+
+    return (
+      <div>
+        <p style={{ marginBottom: '1rem', color: '#64748b', fontSize: '0.875rem' }}>
+          Inspect the tab buttons to see the <code>data-tour</code> and <code>data-testid</code> attributes.
+        </p>
+        <Tabs tabs={tabs} activeTab={activeTab} onChange={setActiveTab} />
+      </div>
+    );
+  },
+};
+
+/**
+ * Compound component pattern with custom data attributes for testing and product tours.
+ */
+export const CompoundWithDataAttributes: Story = {
+  render: () => (
+    <TabsRoot defaultValue="account">
+      <TabsList>
+        <TabsTrigger
+          value="account"
+          icon={<User className="h-4 w-4" />}
+          dataAttributes={{
+            'data-tour': 'compound-tab-account',
+            'data-testid': 'compound-tab-account',
+          }}
+        >
+          Account
+        </TabsTrigger>
+        <TabsTrigger
+          value="password"
+          icon={<Lock className="h-4 w-4" />}
+          dataAttributes={{
+            'data-tour': 'compound-tab-password',
+            'data-testid': 'compound-tab-password',
+          }}
+        >
+          Password
+        </TabsTrigger>
+        <TabsTrigger
+          value="settings"
+          icon={<Settings className="h-4 w-4" />}
+          dataAttributes={{
+            'data-tour': 'compound-tab-settings',
+            'data-testid': 'compound-tab-settings',
+          }}
+        >
+          Settings
+        </TabsTrigger>
+      </TabsList>
+      <TabsContent value="account">
+        <div style={{ padding: '1rem' }}>
+          <h3>Account Settings</h3>
+          <p>Manage your account information and preferences.</p>
+        </div>
+      </TabsContent>
+      <TabsContent value="password">
+        <div style={{ padding: '1rem' }}>
+          <h3>Password Settings</h3>
+          <p>Change your password and security settings.</p>
+        </div>
+      </TabsContent>
+      <TabsContent value="settings">
+        <div style={{ padding: '1rem' }}>
+          <h3>Application Settings</h3>
+          <p>Configure application preferences.</p>
+        </div>
+      </TabsContent>
+    </TabsRoot>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+The compound component pattern also supports \`dataAttributes\` on the \`TabsTrigger\` component.
+This allows targeting individual tabs with selectors like \`[data-tour="compound-tab-account"]\`.
+        `,
+      },
+    },
+  },
+};

package/src/components/Tabs.tsx

@@ -18,6 +18,12 @@ export interface Tab {
   badgeVariant?: 'success' | 'warning' | 'error' | 'info' | 'neutral';
   /** Whether this individual tab can be closed (overrides global closeable) */
   closeable?: boolean;
+  /**
+   * Custom data attributes to spread on the tab trigger element.
+   * Useful for product tours (e.g., Driver.js) and E2E testing (Playwright, Cypress).
+   * @example { 'data-tour': 'tab-settings', 'data-testid': 'settings-tab' }
+   */
+  dataAttributes?: Record<string, string>;
 }
 
 export interface TabsProps {
@@ -274,6 +280,12 @@ export interface TabsTriggerProps {
   badgeVariant?: 'success' | 'warning' | 'error' | 'info' | 'neutral';
   /** Additional class name */
   className?: string;
+  /**
+   * Custom data attributes to spread on the tab trigger element.
+   * Useful for product tours (e.g., Driver.js) and E2E testing (Playwright, Cypress).
+   * @example { 'data-tour': 'tab-settings', 'data-testid': 'settings-tab' }
+   */
+  dataAttributes?: Record<string, string>;
 }
 
 /**
@@ -287,6 +299,7 @@ export function TabsTrigger({
   badge,
   badgeVariant = 'info',
   className = '',
+  dataAttributes,
 }: TabsTriggerProps) {
   const { activeTab, setActiveTab, variant, orientation, size, registerTab, unregisterTab } = useTabsContext();
   const isActive = activeTab === value;
@@ -332,6 +345,8 @@ export function TabsTrigger({
         focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-500 focus-visible:ring-offset-1
         ${className}
       `}
+      data-testid={dataAttributes?.['data-testid'] || `tab-${value}`}
+      {...dataAttributes}
     >
       {icon && <span className={`flex-shrink-0 ${sizeClasses[size].icon}`}>{icon}</span>}
       <span>{children}</span>
@@ -660,6 +675,8 @@ export default function Tabs({
                 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-500 focus-visible:ring-offset-1
                 group
               `}
+              data-testid={tab.dataAttributes?.['data-testid'] || `tab-${tab.id}`}
+              {...tab.dataAttributes}
             >
               {tab.icon && <span className={`flex-shrink-0 ${sizeClasses[size].icon}`}>{tab.icon}</span>}
               <span className={isTabCloseable ? 'mr-1' : ''}>{tab.label}</span>

package/src/components/index.ts

@@ -144,6 +144,9 @@ export type { TooltipProps } from './Tooltip';
 export { default as HelpTooltip } from './HelpTooltip';
 export type { HelpTooltipProps } from './HelpTooltip';
 
+export { default as SkipLink } from './SkipLink';
+export type { SkipLinkProps } from './SkipLink';
+
 export { default as Popover } from './Popover';
 export type { PopoverProps } from './Popover';