@object-ui/components 0.5.0 → 3.0.0

package/src/stories/MockedData.stories.tsx

@@ -1,71 +1,121 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import React, { useEffect, useState } from 'react';
+import React, { useEffect, useState, useCallback } from 'react';
 import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
-import { PageSchema } from '@object-ui/types';
+import type { BaseSchema } from '@object-ui/types';
+import { createStorybookDataSource } from '@storybook-config/datasource';
 
-// Define a schema that binds to fetched data
-const contactDetailSchema: PageSchema = {
+// ==========================================
+// Story 1: Static Data Binding
+// ==========================================
+// Demonstrates how JSON schemas can reference data via expressions like ${data.field}
+
+const staticDataSchema: BaseSchema = {
     type: "page",
-    props: { title: "Contact Details (Mocked)" },
+    props: { title: "Static Data Binding" },
     children: [
         {
             type: "page:header",
             props: {
-                title: "${data.name}", 
-                description: "${data.title} at ${data.company}"
+                title: "Sarah Connors",
+                description: "Lead Engineer at Cyberdyne Systems"
             }
         },
         {
-            type: "view:simple", 
-            props: { columns: 2, className: "mt-4 border p-4 rounded" },
+            type: "grid",
+            props: { cols: 2, gap: 4, className: "mt-4" },
             children: [
-                { type: "field:text", bind: "name", props: { label: "Full Name", readonly: true } },
-                { type: "field:email", bind: "email", props: { label: "Email", readonly: true } },
-                { type: "field:text", bind: "status", props: { label: "Status", readonly: true } }
+                { type: "card", title: "Full Name", children: [{ type: "text", content: "Sarah Connors" }] },
+                { type: "card", title: "Email", children: [{ type: "text", content: "sarah@cyberdyne.com" }] },
+                { type: "card", title: "Status", children: [{ type: "badge", props: { variant: "default", children: "Active" } }] },
+                { type: "card", title: "Department", children: [{ type: "text", content: "Engineering" }] },
             ]
         }
     ]
 };
 
-// A wrapper component that fetches data from the MSW mock
-const DataFetcher = () => {
-    const [data, setData] = useState<any>(null);
+// ==========================================
+// Story 2: MSW-Backed Data (Live API)
+// ==========================================
+// The ObjectStack kernel seeds CRM data via MSW. This story fetches contacts from /api/v1.
 
-    useEffect(() => {
-        // Simulate a fetch call locally since MSW might not be configured in this environment
-        const mockData = {
-            name: "Sarah Connors",
-            title: "Lead Engineer",
-            company: "Cyberdyne Systems",
-            email: "sarah@cyberdyne.com",
-            status: "Active"
-        };
+const dataSource = createStorybookDataSource();
 
-        const timer = setTimeout(() => {
-            setData(mockData);
-        }, 800);
+const ContactListFromAPI = () => {
+    const [contacts, setContacts] = useState<any[]>([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<string | null>(null);
 
-        return () => clearTimeout(timer);
+    const fetchContacts = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const result = await dataSource.find('contact', { $top: 10 });
+            setContacts(result.data as any[]);
+        } catch (err: any) {
+            console.error('[Data Binding] Failed to fetch contacts:', err);
+            setError(err?.message || 'Failed to fetch data from MSW API');
+        } finally {
+            setLoading(false);
+        }
     }, []);
 
-    if (!data) return <div className="p-4">Loading data from MSW...</div>;
+    useEffect(() => {
+        fetchContacts();
+    }, [fetchContacts]);
+
+    if (loading) return <div className="p-8 text-muted-foreground">Loading contacts from MSW API...</div>;
+    if (error) return (
+        <div className="p-8 space-y-2">
+            <div className="text-destructive font-medium">API Error: {error}</div>
+            <div className="text-sm text-muted-foreground">
+                This story requires the ObjectStack MSW runtime to be running.
+                Check the browser console for [Storybook MSW] logs.
+            </div>
+        </div>
+    );
+
+    const gridSchema: BaseSchema = {
+        type: 'object-grid',
+        objectName: 'contact',
+        columns: [
+            { field: 'name', header: 'Name', sortable: true },
+            { field: 'email', header: 'Email', sortable: true },
+            { field: 'title', header: 'Title' },
+            { field: 'status', header: 'Status' },
+        ],
+        data: contacts,
+        className: 'w-full'
+    } as any;
 
     return (
-        <SchemaRendererProvider dataSource={data}>
-            <SchemaRenderer schema={contactDetailSchema} />
+        <SchemaRendererProvider dataSource={dataSource}>
+            <div className="space-y-4">
+                <div className="flex items-center justify-between">
+                    <h2 className="text-lg font-semibold">Contacts from MSW ({contacts.length} records)</h2>
+                </div>
+                <SchemaRenderer schema={gridSchema} />
+            </div>
         </SchemaRendererProvider>
     );
 };
 
+// ==========================================
+// Meta
+// ==========================================
+
 const meta: Meta = {
-  title: 'Guide/Mocked Data',
-  component: DataFetcher,
+  title: 'Getting Started/Data Binding',
   parameters: {
-      // We can also override handlers per story here if needed
-      // msw: { handlers: [...] }
-  }
+      layout: 'padded',
+  },
 };
 
 export default meta;
 
-export const Default: StoryObj = {};
+export const StaticData: StoryObj = {
+    render: () => <SchemaRenderer schema={staticDataSchema} />,
+};
+
+export const LiveAPI: StoryObj = {
+    render: () => <ContactListFromAPI />,
+};

package/src/stories-json/Accessibility.mdx

@@ -0,0 +1,297 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Getting Started/Accessibility" />
+
+# Accessibility Reference
+
+ObjectUI targets **WCAG 2.1 Level AA** conformance. Every component inherits accessible
+primitives from [Radix UI](https://www.radix-ui.com/) and is styled with Tailwind CSS
+utility classes that respect user preferences for reduced motion and color contrast.
+
+---
+
+## Compliance Baseline
+
+| Standard | Level | Status |
+|---|---|---|
+| WCAG 2.1 | AA | ✅ Target conformance for all components |
+| WAI-ARIA 1.2 | — | ✅ Roles, states, and properties via Radix |
+| Section 508 | — | ✅ Covered by WCAG AA compliance |
+
+ObjectUI relies on **Radix UI** for its accessible primitive layer. Radix components
+ship with correct ARIA roles, keyboard interactions, and focus management built in.
+Shadcn UI wraps these primitives with Tailwind styling while preserving all accessibility
+behaviour.
+
+---
+
+## Keyboard Navigation Patterns
+
+All interactive components support keyboard navigation following WAI-ARIA authoring
+practices. Below is a reference of the patterns used across component types.
+
+### General Controls
+
+| Component | Key | Action |
+|---|---|---|
+| **Button** | `Enter` / `Space` | Activate the button |
+| **Link** | `Enter` | Follow the link |
+| **Toggle** | `Enter` / `Space` | Toggle the state |
+| All focusable | `Tab` | Move focus to next element |
+| All focusable | `Shift + Tab` | Move focus to previous element |
+
+### Composite Widgets
+
+| Component | Key | Action |
+|---|---|---|
+| **Tabs** | `Arrow Left` / `Arrow Right` | Move between tab triggers |
+| **Tabs** | `Enter` / `Space` | Activate focused tab |
+| **Tabs** | `Home` / `End` | Jump to first / last tab |
+| **Accordion** | `Arrow Up` / `Arrow Down` | Move between headers |
+| **Accordion** | `Enter` / `Space` | Expand / collapse section |
+| **Accordion** | `Home` / `End` | Jump to first / last header |
+| **Menu / DropdownMenu** | `Arrow Up` / `Arrow Down` | Navigate menu items |
+| **Menu / DropdownMenu** | `Enter` / `Space` | Activate item |
+| **Menu / DropdownMenu** | `Escape` | Close menu and return focus |
+| **NavigationMenu** | `Arrow Left` / `Arrow Right` | Move between top-level items |
+| **NavigationMenu** | `Arrow Down` | Open submenu |
+| **NavigationMenu** | `Escape` | Close submenu |
+
+### Form Fields
+
+| Component | Key | Action |
+|---|---|---|
+| **Input / Textarea** | Standard typing | Enter text |
+| **Select** | `Arrow Up` / `Arrow Down` | Navigate options |
+| **Select** | `Enter` | Select option |
+| **Select** | `Escape` | Close listbox |
+| **Checkbox** | `Space` | Toggle checked state |
+| **Radio Group** | `Arrow Up` / `Arrow Down` | Move selection |
+| **Switch** | `Space` | Toggle on/off |
+| **Slider** | `Arrow Left` / `Arrow Right` | Decrease / increase value |
+| **Slider** | `Home` / `End` | Set to minimum / maximum |
+| **DatePicker** | `Arrow Keys` | Navigate calendar grid |
+| **DatePicker** | `Enter` | Select date |
+| **DatePicker** | `Escape` | Close calendar popover |
+
+### Overlay Components
+
+| Component | Key | Action |
+|---|---|---|
+| **Dialog** | `Escape` | Close the dialog |
+| **Dialog** | `Tab` | Cycle focus within dialog (focus trap) |
+| **AlertDialog** | `Escape` | Close (if not critical) |
+| **AlertDialog** | `Tab` | Cycle focus within alert |
+| **Popover** | `Escape` | Close popover |
+| **Tooltip** | `Escape` | Dismiss tooltip |
+| **Sheet** | `Escape` | Close sheet overlay |
+| **Sheet** | `Tab` | Cycle focus within sheet |
+
+### Data Views (Plugins)
+
+| Component | Key | Action |
+|---|---|---|
+| **DataTable / Grid** | `Arrow Keys` | Navigate cells |
+| **DataTable / Grid** | `Enter` | Activate cell / begin editing |
+| **DataTable / Grid** | `Escape` | Cancel editing |
+| **DataTable / Grid** | `Tab` | Move to next focusable cell |
+| **Kanban** | `Tab` | Move between cards |
+| **Kanban** | `Enter` / `Space` | Open card detail |
+
+---
+
+## ARIA Roles and Attributes
+
+ObjectUI components emit the correct ARIA roles and attributes automatically through
+Radix primitives. Below is a reference of the key mappings.
+
+### Primitive Components
+
+| Component | ARIA Role | Key Attributes |
+|---|---|---|
+| **Button** | `button` | `aria-disabled`, `aria-pressed` (toggle) |
+| **Badge** | `status` | `aria-label` (when used as status indicator) |
+| **Card** | `region` | `aria-labelledby` (card title) |
+| **Separator** | `separator` | `aria-orientation` |
+| **Avatar** | `img` | `alt` text on image, fallback initials |
+| **Progress** | `progressbar` | `aria-valuenow`, `aria-valuemin`, `aria-valuemax` |
+| **Skeleton** | `status` | `aria-busy="true"`, `aria-label="Loading"` |
+
+### Composite Components
+
+| Component | ARIA Role | Key Attributes |
+|---|---|---|
+| **Tabs** | `tablist`, `tab`, `tabpanel` | `aria-selected`, `aria-controls`, `aria-labelledby` |
+| **Accordion** | `region` | `aria-expanded`, `aria-controls` on triggers |
+| **Breadcrumb** | `navigation` | `aria-label="Breadcrumb"`, `aria-current="page"` on active |
+| **NavigationMenu** | `navigation` | `aria-label`, `aria-expanded` on submenus |
+| **Carousel** | `region` | `aria-roledescription="carousel"`, `aria-label` on slides |
+
+### Form Components
+
+| Component | ARIA Role | Key Attributes |
+|---|---|---|
+| **Input** | `textbox` | `aria-required`, `aria-invalid`, `aria-describedby` (error/hint) |
+| **Textarea** | `textbox` | `aria-required`, `aria-invalid`, `aria-describedby` |
+| **Select** | `combobox` / `listbox` | `aria-expanded`, `aria-activedescendant`, `aria-required` |
+| **Checkbox** | `checkbox` | `aria-checked`, `aria-required` |
+| **Radio Group** | `radiogroup`, `radio` | `aria-checked`, `aria-required` |
+| **Switch** | `switch` | `aria-checked`, `aria-label` |
+| **Slider** | `slider` | `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-label` |
+| **Label** | — | `for` / `htmlFor` association with input |
+
+### Overlay Components
+
+| Component | ARIA Role | Key Attributes |
+|---|---|---|
+| **Dialog** | `dialog` | `aria-modal="true"`, `aria-labelledby`, `aria-describedby` |
+| **AlertDialog** | `alertdialog` | `aria-modal="true"`, `aria-labelledby`, `aria-describedby` |
+| **Popover** | `dialog` | `aria-expanded` on trigger, auto `aria-labelledby` |
+| **Tooltip** | `tooltip` | `aria-describedby` on trigger element |
+| **Sheet** | `dialog` | `aria-modal="true"`, `aria-labelledby` |
+| **DropdownMenu** | `menu`, `menuitem` | `aria-expanded`, `aria-haspopup` |
+| **ContextMenu** | `menu`, `menuitem` | `aria-expanded`, `aria-haspopup` |
+
+### Data View Components
+
+| Component | ARIA Role | Key Attributes |
+|---|---|---|
+| **DataTable** | `table`, `row`, `cell` | `aria-sort` on sortable columns, `aria-rowcount` |
+| **Grid (AG Grid)** | `grid`, `row`, `gridcell` | `aria-colcount`, `aria-rowindex`, `aria-selected` |
+| **Kanban** | `list`, `listitem` | `aria-label` per column, `aria-grabbed` on draggable cards |
+
+---
+
+## Screen Reader Behaviour
+
+ObjectUI components are designed to work seamlessly with screen readers
+(NVDA, JAWS, VoiceOver, TalkBack). Key behaviours include:
+
+### Focus Management
+- **Dialogs and Sheets** trap focus within the overlay while open. On close, focus
+  returns to the trigger element.
+- **Menus and Popovers** return focus to their trigger on dismiss.
+- **Toast notifications** use `role="status"` with `aria-live="polite"` so screen
+  readers announce them without interrupting the user.
+
+### Live Regions
+- **Form validation errors** are linked via `aria-describedby`, so errors are announced
+  when the field receives focus.
+- **Loading states** use `aria-busy="true"` on the loading container and `aria-live`
+  regions to announce completion.
+- **Toast / Alert** components use `aria-live="polite"` or `aria-live="assertive"`
+  depending on urgency.
+
+### Landmark Regions
+- **AppShell** emits `<header>`, `<nav>`, `<main>`, and `<aside>` landmarks so screen
+  reader users can jump between sections.
+- **Breadcrumb** uses `<nav aria-label="Breadcrumb">` for quick landmark navigation.
+- **Sidebar** uses `<aside>` with a descriptive `aria-label`.
+
+### Announcements
+- **Sortable table columns** announce sort direction changes via `aria-sort`.
+- **Accordion** sections announce expanded/collapsed state.
+- **Tabs** announce the active tab label on selection.
+- **Carousel** announces slide transitions with `aria-roledescription`.
+
+---
+
+## Color Contrast Requirements
+
+ObjectUI uses Tailwind CSS design tokens (CSS custom properties) for all color
+values. The default theme meets WCAG AA contrast ratios:
+
+| Element | Minimum Ratio | Standard |
+|---|---|---|
+| Body text (`foreground` on `background`) | **4.5 : 1** | WCAG AA — Normal text |
+| Large text (≥ 18pt or ≥ 14pt bold) | **3 : 1** | WCAG AA — Large text |
+| UI components and graphical objects | **3 : 1** | WCAG 2.1 SC 1.4.11 |
+| Focus indicators | **3 : 1** | WCAG 2.1 SC 1.4.11 |
+
+### Theme Tokens
+
+All colors are defined as CSS variables in HSL format:
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222 84% 5%;
+  --primary: 222 47% 11%;
+  --primary-foreground: 210 40% 98%;
+  --destructive: 0 84% 60%;
+  --destructive-foreground: 0 0% 98%;
+  --muted: 210 40% 96%;
+  --muted-foreground: 215 16% 47%;
+  /* ...additional tokens */
+}
+```
+
+When customising tokens, verify contrast ratios with a tool such as the
+[WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) or the
+built-in Storybook accessibility panel.
+
+### Dark Mode
+
+ObjectUI supports a `.dark` class on the root element. The dark theme ships with
+its own set of tokens that maintain the same contrast ratios:
+
+```css
+.dark {
+  --background: 222 84% 5%;
+  --foreground: 210 40% 98%;
+  /* ...dark tokens */
+}
+```
+
+### Focus Indicators
+
+All interactive elements display a visible focus ring when navigated via keyboard.
+The default ring uses the `--ring` token and applies a `2px` outline with a `2px`
+offset, ensuring it meets the **3 : 1** non-text contrast requirement.
+
+```css
+:root {
+  --ring: 222 47% 11%;
+}
+```
+
+> **Tip:** Never remove focus outlines (`outline: none`) without providing an
+> equivalent visible indicator. ObjectUI's `focus-visible` styles handle this
+> automatically.
+
+---
+
+## Testing Accessibility
+
+### Storybook A11y Addon
+
+Every story in this Storybook can be audited via the **Accessibility** panel in the
+addons bar. It runs [axe-core](https://github.com/dequelabs/axe-core) checks and
+reports violations, passes, and incomplete audits.
+
+### Automated Testing
+
+Use `vitest` with `@testing-library/jest-dom` matchers for assertions like
+`toBeVisible()`, `toHaveAccessibleName()`, and `toHaveAttribute('aria-expanded')`.
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+it('Button has no accessibility violations', async () => {
+  const { container } = render(<Button>Click me</Button>);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+### Manual Testing Checklist
+
+- [ ] Navigate all interactive elements using only the keyboard (`Tab`, `Enter`, `Space`, `Escape`, `Arrow` keys).
+- [ ] Verify visible focus indicators on every focusable element.
+- [ ] Test with a screen reader (VoiceOver on macOS, NVDA on Windows).
+- [ ] Check colour contrast using the browser DevTools or WebAIM checker.
+- [ ] Confirm the page is usable at 200% browser zoom.
+- [ ] Verify `prefers-reduced-motion` is respected (animations are disabled or reduced).

package/src/stories-json/EdgeCases.stories.tsx

@@ -0,0 +1,160 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { SchemaRenderer } from '../SchemaRenderer';
+import type { BaseSchema } from '@object-ui/types';
+
+const meta = {
+  title: 'Components / Edge Cases',
+  component: SchemaRenderer,
+  parameters: { layout: 'padded' },
+  tags: ['autodocs'],
+  argTypes: {
+    schema: { table: { disable: true } },
+  },
+} satisfies Meta<any>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const renderStory = (args: any) => <SchemaRenderer schema={args as unknown as BaseSchema} />;
+
+// ── Empty States ──────────────────────────────────────────────
+
+export const EmptyStateDefault: Story = {
+  name: 'Empty State – Default',
+  render: renderStory,
+  args: {
+    type: 'empty',
+    description: 'No items to display',
+  } as any,
+};
+
+export const EmptyStateWithAction: Story = {
+  name: 'Empty State – With Action',
+  render: renderStory,
+  args: {
+    type: 'empty',
+    description: 'No results found. Try a different search or create a new item.',
+    children: [
+      { type: 'button', content: 'Create New', variant: 'default', size: 'sm' },
+    ],
+  } as any,
+};
+
+// ── Loading / Spinner ─────────────────────────────────────────
+
+export const SpinnerSmall: Story = {
+  name: 'Spinner – Small',
+  render: renderStory,
+  args: {
+    type: 'spinner',
+    size: 'sm',
+    className: 'text-primary',
+  } as any,
+};
+
+export const SpinnerLarge: Story = {
+  name: 'Spinner – Large',
+  render: renderStory,
+  args: {
+    type: 'spinner',
+    size: 'lg',
+    className: 'text-primary',
+  } as any,
+};
+
+export const LoadingWithText: Story = {
+  name: 'Loading – With Text',
+  render: renderStory,
+  args: {
+    type: 'loading',
+    text: 'Please wait while we fetch your data…',
+    className: 'h-[200px]',
+  } as any,
+};
+
+// ── Overflow / Long Text ──────────────────────────────────────
+
+const LONG_TEXT =
+  'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit.';
+
+export const CardWithLongText: Story = {
+  name: 'Card – Very Long Text',
+  render: renderStory,
+  args: {
+    type: 'card',
+    className: 'w-[350px]',
+    title: 'This is an extremely long card title that should test how the component handles overflow and text wrapping gracefully',
+    description: LONG_TEXT,
+    children: [
+      {
+        type: 'text',
+        content: LONG_TEXT + ' ' + LONG_TEXT,
+      },
+    ],
+  } as any,
+};
+
+export const BadgeWithLongText: Story = {
+  name: 'Badge – Very Long Text',
+  render: renderStory,
+  args: {
+    type: 'badge',
+    label: 'This is an unusually long badge label that tests truncation and overflow behaviour in tight layouts',
+  } as any,
+};
+
+export const ButtonWithIconAndLongText: Story = {
+  name: 'Button – Icon + Long Text',
+  render: (args: any) => <SchemaRenderer schema={args as unknown as BaseSchema} />,
+  args: {
+    type: 'button',
+    props: { variant: 'default' },
+    children: [
+      { type: 'icon', name: 'download', className: 'mr-2 h-4 w-4' },
+      {
+        type: 'text',
+        content: 'Download All Reports For The Current Financial Year Including Amendments',
+      },
+    ],
+  } as any,
+};
+
+// ── RTL Layout ────────────────────────────────────────────────
+
+export const RTLCard: Story = {
+  name: 'RTL – Card Layout',
+  render: (args: any) => (
+    <div dir="rtl">
+      <SchemaRenderer schema={args as unknown as BaseSchema} />
+    </div>
+  ),
+  args: {
+    type: 'card',
+    className: 'w-[350px]',
+    title: 'عنوان البطاقة',
+    description: 'هذا النص باللغة العربية لاختبار تخطيط الاتجاه من اليمين إلى اليسار.',
+    children: [
+      { type: 'text', content: 'محتوى البطاقة الرئيسي يظهر هنا باللغة العربية.' },
+    ],
+    footer: [
+      { type: 'button', props: { variant: 'outline' }, children: [{ type: 'text', content: 'إلغاء' }] },
+      { type: 'button', children: [{ type: 'text', content: 'حفظ' }] },
+    ],
+  } as any,
+};
+
+export const RTLAlert: Story = {
+  name: 'RTL – Alert',
+  render: (args: any) => (
+    <div dir="rtl">
+      <SchemaRenderer schema={args as unknown as BaseSchema} />
+    </div>
+  ),
+  args: {
+    type: 'alert',
+    variant: 'destructive',
+    title: 'خطأ',
+    description: 'انتهت صلاحية الجلسة. الرجاء تسجيل الدخول مرة أخرى.',
+    className: 'w-[400px]',
+  } as any,
+};