@fragments-sdk/ui 0.8.1 → 0.8.2

package/src/components/Input/index.tsx

@@ -15,7 +15,7 @@ export interface InputProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
   error?: boolean;
   label?: string;
   helperText?: string;
-  /** Keyboard shortcut hint displayed inside the input (e.g., "⌘K") */
+  /** Keyboard shortcut hint displayed inside the input (e.g., "⌘K"). Also registers a global keydown listener that focuses the input when the shortcut is pressed. */
   shortcut?: string;
   onChange?: (value: string) => void;
   onBlur?: () => void;
@@ -33,6 +33,20 @@ function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
   return merged.length > 0 ? merged : undefined;
 }
 
+function parseShortcut(shortcut: string): { meta: boolean; shift: boolean; alt: boolean; key: string } | null {
+  let meta = false, shift = false, alt = false;
+  let remaining = shortcut;
+
+  if (remaining.includes('⌘')) { meta = true; remaining = remaining.replace('⌘', ''); }
+  if (remaining.includes('⇧')) { shift = true; remaining = remaining.replace('⇧', ''); }
+  if (remaining.includes('⌥')) { alt = true; remaining = remaining.replace('⌥', ''); }
+
+  remaining = remaining.trim();
+  if (!remaining) return null;
+
+  return { meta, shift, alt, key: remaining };
+}
+
 const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(
   function Input(
     {
@@ -66,6 +80,37 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(
     const generatedId = React.useId();
     const helperId = helperText ? `input-helper-${generatedId}` : undefined;
 
+    const internalRef = React.useRef<HTMLInputElement>(null);
+    const mergedRef = React.useCallback(
+      (node: HTMLInputElement | null) => {
+        internalRef.current = node;
+        if (typeof ref === 'function') {
+          ref(node);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLInputElement | null>).current = node;
+        }
+      },
+      [ref]
+    );
+
+    // Register global keydown handler when shortcut is provided
+    React.useEffect(() => {
+      if (!shortcut) return;
+      const parsed = parseShortcut(shortcut);
+      if (!parsed) return;
+
+      const handler = (e: KeyboardEvent) => {
+        if (parsed.meta && !(e.metaKey || e.ctrlKey)) return;
+        if (parsed.shift && !e.shiftKey) return;
+        if (parsed.alt && !e.altKey) return;
+        if (e.key.toLowerCase() !== parsed.key.toLowerCase()) return;
+        e.preventDefault();
+        internalRef.current?.focus();
+      };
+      document.addEventListener('keydown', handler);
+      return () => document.removeEventListener('keydown', handler);
+    }, [shortcut]);
+
     const inputClasses = [
       styles.input,
       styles[size],
@@ -85,7 +130,7 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(
 
     const inputElement = (
       <Field.Control
-        ref={ref}
+        ref={mergedRef}
         type={type}
         value={value}
         defaultValue={defaultValue}

package/src/components/Menu/Menu.module.scss

@@ -11,6 +11,8 @@
 .popup {
   @include surface-elevated;
 
+  list-style: none;
+  margin: 0;
   min-width: 12rem;
   padding: var(--fui-padding-item-xs, $fui-padding-item-xs);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);

package/src/components/Table/Table.fragment.tsx

@@ -58,7 +58,7 @@ export default defineFragment({
     ],
     whenNot: [
       'Simple lists (use List component)',
-      'Card-based layouts (use CardGrid)',
+      'Card-based layouts (use Grid with Cards)',
       'Heavily interactive data (consider DataGrid)',
       'Small screens (consider card or list view)',
     ],

package/src/components/ToggleGroup/ToggleGroup.fragment.tsx

@@ -194,31 +194,63 @@ export default defineFragment({
     {
       name: 'Default',
       description: 'Basic toggle group',
+      code: `<ToggleGroup value={value} onChange={setValue}>
+  <ToggleGroup.Item value="left">Left</ToggleGroup.Item>
+  <ToggleGroup.Item value="center">Center</ToggleGroup.Item>
+  <ToggleGroup.Item value="right">Right</ToggleGroup.Item>
+</ToggleGroup>`,
       render: () => <DefaultExample />,
     },
     {
       name: 'Pills Variant',
       description: 'Pill-shaped toggle buttons',
+      code: `<ToggleGroup value={value} onChange={setValue} variant="pills">
+  <ToggleGroup.Item value="all">All</ToggleGroup.Item>
+  <ToggleGroup.Item value="active">Active</ToggleGroup.Item>
+  <ToggleGroup.Item value="completed">Completed</ToggleGroup.Item>
+</ToggleGroup>`,
       render: () => <PillsExample />,
     },
     {
       name: 'Outline Variant',
       description: 'Outlined toggle buttons',
+      code: `<ToggleGroup value={value} onChange={setValue} variant="outline">
+  <ToggleGroup.Item value="day">Day</ToggleGroup.Item>
+  <ToggleGroup.Item value="week">Week</ToggleGroup.Item>
+  <ToggleGroup.Item value="month">Month</ToggleGroup.Item>
+</ToggleGroup>`,
       render: () => <OutlineExample />,
     },
     {
       name: 'Sizes',
       description: 'Different size variants',
+      code: `<ToggleGroup value={value} onChange={setValue} size="sm">
+  <ToggleGroup.Item value="a">Small</ToggleGroup.Item>
+  <ToggleGroup.Item value="b">Size</ToggleGroup.Item>
+</ToggleGroup>
+<ToggleGroup value={value} onChange={setValue} size="md">
+  <ToggleGroup.Item value="a">Medium</ToggleGroup.Item>
+  <ToggleGroup.Item value="b">Size</ToggleGroup.Item>
+</ToggleGroup>`,
       render: () => <SizesExample />,
     },
     {
       name: 'View Switcher',
       description: 'Common pattern for switching between views',
+      code: `<ToggleGroup value={view} onChange={setView} size="sm">
+  <ToggleGroup.Item value="grid"><GridIcon /></ToggleGroup.Item>
+  <ToggleGroup.Item value="list"><ListIcon /></ToggleGroup.Item>
+</ToggleGroup>`,
       render: () => <ViewSwitcherExample />,
     },
     {
       name: 'With Disabled Item',
       description: 'Toggle group with a disabled option',
+      code: `<ToggleGroup value={value} onChange={setValue}>
+  <ToggleGroup.Item value="basic">Basic</ToggleGroup.Item>
+  <ToggleGroup.Item value="pro">Pro</ToggleGroup.Item>
+  <ToggleGroup.Item value="enterprise" disabled>Enterprise</ToggleGroup.Item>
+</ToggleGroup>`,
       render: () => <DisabledItemExample />,
     },
   ],

package/src/index.ts

@@ -521,6 +521,9 @@ export {
   type ChartLegendContentProps,
 } from './components/Chart';
 
+// Assets
+export { FragmentsLogo, type FragmentsLogoProps } from './assets/fragments-logo';
+
 // Accessibility Utilities
 export {
   useId,

package/src/tokens/_derive.scss

@@ -46,30 +46,54 @@
 // --------------------------------------------
 
 /// Derive hover state for accent color
+/// Handles extreme lightness values (near-black/near-white) by reversing
+/// the adjustment direction to ensure a visible hover state.
 /// @param {Color} $base - Base accent color
 /// @param {Boolean} $is-dark - Whether in dark mode
 /// @return {Color} Hover state color
 @function derive-accent-hover($base, $is-dark: false) {
+  $l: color.channel($base, 'lightness', $space: hsl);
+
   @if $is-dark {
-    // In dark mode, lighten for hover
-    @return color.scale($base, $lightness: 5%);
+    @if $l > 85% {
+      // Very light accent on dark bg: darken for visible hover
+      @return color.scale($base, $lightness: -10%);
+    }
+    // Standard dark mode: lighten for hover
+    @return color.scale($base, $lightness: 8%);
   } @else {
-    // In light mode, darken for hover
-    @return color.scale($base, $lightness: -8%);
+    @if $l < 15% {
+      // Very dark accent on light bg: lighten for visible hover
+      @return color.scale($base, $lightness: 18%);
+    }
+    // Standard light mode: darken for hover
+    @return color.scale($base, $lightness: -10%);
   }
 }
 
 /// Derive active state for accent color
+/// Handles extreme lightness values (near-black/near-white) by reversing
+/// the adjustment direction to ensure a visible active/pressed state.
 /// @param {Color} $base - Base accent color
 /// @param {Boolean} $is-dark - Whether in dark mode
 /// @return {Color} Active state color
 @function derive-accent-active($base, $is-dark: false) {
+  $l: color.channel($base, 'lightness', $space: hsl);
+
   @if $is-dark {
-    // In dark mode, lighten more for active
-    @return color.scale($base, $lightness: 10%);
+    @if $l > 85% {
+      // Very light accent on dark bg: darken more for active
+      @return color.scale($base, $lightness: -16%);
+    }
+    // Standard dark mode: lighten more for active
+    @return color.scale($base, $lightness: 14%);
   } @else {
-    // In light mode, darken more for active
-    @return color.scale($base, $lightness: -15%);
+    @if $l < 15% {
+      // Very dark accent on light bg: lighten more for active
+      @return color.scale($base, $lightness: 28%);
+    }
+    // Standard light mode: darken more for active
+    @return color.scale($base, $lightness: -18%);
   }
 }
 

package/src/blocks/AIChat.block.ts

@@ -1,266 +0,0 @@
-import { defineBlock } from '@fragments/core';
-
-export default defineBlock({
-  name: 'AI Chat',
-  description: 'Complete AI chat interface with Message, ConversationList, Prompt, and ThinkingIndicator',
-  category: 'ai',
-  components: ['Message', 'ConversationList', 'ThinkingIndicator', 'Prompt', 'Stack'],
-  tags: ['chat', 'ai', 'assistant', 'conversation', 'llm', 'chatbot'],
-  code: `
-import { useState, useCallback } from 'react';
-import {
-  Message,
-  ConversationList,
-  ThinkingIndicator,
-  Prompt,
-  Stack,
-} from '@fragments/ui';
-
-interface ChatMessage {
-  id: string;
-  role: 'user' | 'assistant' | 'system';
-  content: string;
-  timestamp: Date;
-  status?: 'sending' | 'streaming' | 'complete' | 'error';
-}
-
-interface ThinkingStep {
-  id: string;
-  label: string;
-  status: 'pending' | 'active' | 'complete' | 'error';
-}
-
-function AIChat() {
-  const [messages, setMessages] = useState<ChatMessage[]>([
-    {
-      id: 'system-1',
-      role: 'system',
-      content: 'Conversation started. Model: Claude 3.5 Sonnet',
-      timestamp: new Date(),
-      status: 'complete',
-    },
-  ]);
-  const [isThinking, setIsThinking] = useState(false);
-  const [thinkingSteps, setThinkingSteps] = useState<ThinkingStep[]>([]);
-  const [isLoadingHistory, setIsLoadingHistory] = useState(false);
-
-  const handleSubmit = useCallback(async (value: string) => {
-    // Add user message
-    const userMessage: ChatMessage = {
-      id: crypto.randomUUID(),
-      role: 'user',
-      content: value,
-      timestamp: new Date(),
-      status: 'complete',
-    };
-    setMessages((prev) => [...prev, userMessage]);
-
-    // Start thinking state with steps
-    setIsThinking(true);
-    setThinkingSteps([
-      { id: '1', label: 'Understanding your request', status: 'active' },
-      { id: '2', label: 'Searching knowledge base', status: 'pending' },
-      { id: '3', label: 'Generating response', status: 'pending' },
-    ]);
-
-    try {
-      // Simulate step 1 completion
-      await new Promise((resolve) => setTimeout(resolve, 800));
-      setThinkingSteps((prev) =>
-        prev.map((s) =>
-          s.id === '1'
-            ? { ...s, status: 'complete' }
-            : s.id === '2'
-              ? { ...s, status: 'active' }
-              : s
-        )
-      );
-
-      // Simulate step 2 completion
-      await new Promise((resolve) => setTimeout(resolve, 600));
-      setThinkingSteps((prev) =>
-        prev.map((s) =>
-          s.id === '2'
-            ? { ...s, status: 'complete' }
-            : s.id === '3'
-              ? { ...s, status: 'active' }
-              : s
-        )
-      );
-
-      // Simulate step 3 (response generation)
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-
-      // Add assistant response
-      const assistantMessage: ChatMessage = {
-        id: crypto.randomUUID(),
-        role: 'assistant',
-        content: generateMockResponse(value),
-        timestamp: new Date(),
-        status: 'complete',
-      };
-      setMessages((prev) => [...prev, assistantMessage]);
-    } catch (error) {
-      // Handle error
-      const errorMessage: ChatMessage = {
-        id: crypto.randomUUID(),
-        role: 'assistant',
-        content: 'Sorry, I encountered an error. Please try again.',
-        timestamp: new Date(),
-        status: 'error',
-      };
-      setMessages((prev) => [...prev, errorMessage]);
-    } finally {
-      setIsThinking(false);
-      setThinkingSteps([]);
-    }
-  }, []);
-
-  const handleLoadHistory = useCallback(async () => {
-    if (isLoadingHistory) return;
-
-    setIsLoadingHistory(true);
-    await new Promise((resolve) => setTimeout(resolve, 1500));
-
-    // Simulate loading older messages
-    const olderMessages: ChatMessage[] = [
-      {
-        id: crypto.randomUUID(),
-        role: 'user',
-        content: 'What can you help me with?',
-        timestamp: new Date(Date.now() - 86400000), // Yesterday
-        status: 'complete',
-      },
-      {
-        id: crypto.randomUUID(),
-        role: 'assistant',
-        content: 'I can help with coding, writing, analysis, and more!',
-        timestamp: new Date(Date.now() - 86400000 + 1000),
-        status: 'complete',
-      },
-    ];
-
-    setMessages((prev) => [...olderMessages, ...prev]);
-    setIsLoadingHistory(false);
-  }, [isLoadingHistory]);
-
-  const handleCopy = useCallback((content: string) => {
-    navigator.clipboard.writeText(content);
-    // You might want to show a toast here
-  }, []);
-
-  return (
-    <Stack
-      style={{
-        height: '100vh',
-        maxWidth: '800px',
-        margin: '0 auto',
-        background: 'var(--fui-bg-primary)',
-      }}
-    >
-      <ConversationList
-        autoScroll="smart"
-        onScrollTop={handleLoadHistory}
-        loadingHistory={isLoadingHistory}
-        emptyState={
-          <Stack align="center" justify="center" style={{ flex: 1, padding: '2rem' }}>
-            <p style={{ color: 'var(--fui-text-secondary)' }}>
-              Start a conversation with the AI assistant
-            </p>
-          </Stack>
-        }
-      >
-        {messages.map((msg, index) => {
-          // Add date separator if day changed
-          const prevMsg = messages[index - 1];
-          const showDateSeparator =
-            !prevMsg ||
-            new Date(msg.timestamp).toDateString() !==
-              new Date(prevMsg.timestamp).toDateString();
-
-          return (
-            <React.Fragment key={msg.id}>
-              {showDateSeparator && (
-                <ConversationList.DateSeparator date={msg.timestamp} />
-              )}
-              <Message
-                role={msg.role}
-                status={msg.status}
-                timestamp={msg.timestamp}
-                actions={
-                  msg.role === 'assistant' && msg.status === 'complete' ? (
-                    <>
-                      <button
-                        onClick={() => handleCopy(msg.content)}
-                        style={{
-                          padding: '4px 8px',
-                          fontSize: '12px',
-                          background: 'var(--fui-bg-tertiary)',
-                          border: 'none',
-                          borderRadius: '4px',
-                          cursor: 'pointer',
-                        }}
-                      >
-                        Copy
-                      </button>
-                    </>
-                  ) : undefined
-                }
-              >
-                <Message.Content>{msg.content}</Message.Content>
-                {msg.timestamp && <Message.Timestamp />}
-              </Message>
-            </React.Fragment>
-          );
-        })}
-
-        {isThinking && (
-          <ThinkingIndicator
-            variant="dots"
-            label="Claude is thinking..."
-            showElapsed
-            steps={thinkingSteps}
-          />
-        )}
-      </ConversationList>
-
-      <div style={{ padding: '1rem', borderTop: '1px solid var(--fui-border)' }}>
-        <Prompt
-          onSubmit={handleSubmit}
-          loading={isThinking}
-          placeholder="Message Claude..."
-        >
-          <Prompt.Textarea />
-          <Prompt.Toolbar>
-            <Prompt.Actions>
-              <Prompt.ActionButton aria-label="Attach file">
-                +
-              </Prompt.ActionButton>
-              <Prompt.ModeButton active>Auto</Prompt.ModeButton>
-            </Prompt.Actions>
-            <Prompt.Info>
-              <Prompt.Submit />
-            </Prompt.Info>
-          </Prompt.Toolbar>
-        </Prompt>
-      </div>
-    </Stack>
-  );
-}
-
-// Mock response generator
-function generateMockResponse(input: string): string {
-  const responses = [
-    "That's a great question! Let me help you with that.",
-    "I understand what you're looking for. Here's what I can tell you...",
-    "Based on my knowledge, I can provide some insights on this topic.",
-    "Let me break this down for you step by step.",
-  ];
-  return responses[Math.floor(Math.random() * responses.length)] +
-    " This is a simulated response. In a real implementation, this would be replaced with actual AI-generated content based on your query about: " +
-    input.substring(0, 50) + (input.length > 50 ? '...' : '');
-}
-
-export default AIChat;
-`.trim(),
-});

package/src/blocks/AppShell.block.ts

@@ -1,175 +0,0 @@
-import { defineBlock } from '@fragments/core';
-
-export default defineBlock({
-  name: 'App Shell',
-  description: 'Full application layout with sidebar, header, and main content. Supports two layout modes: stacked (header full-width) and sidebar-inset (sidebar full-height).',
-  category: 'layout',
-  components: ['AppShell', 'Header', 'Sidebar', 'Theme'],
-  tags: ['layout', 'app-shell', 'sidebar', 'navigation', 'dashboard'],
-  code: `
-// App Shell - Stacked Layout (header spans full width)
-// Best for apps where the brand should be prominent in the header
-
-import { AppShell, Header, Input, Sidebar, ThemeToggle } from '@fragments-sdk/ui';
-
-function StackedLayout({ children }) {
-  return (
-    <AppShell layout="stacked">
-      <AppShell.Header>
-        <Header>
-          <Header.SkipLink />
-          <Header.Trigger />
-          <Header.Brand href="/">MyApp</Header.Brand>
-          <Header.Nav>
-            <Header.NavItem href="/" active>Dashboard</Header.NavItem>
-            <Header.NavItem href="/settings">Settings</Header.NavItem>
-          </Header.Nav>
-          <Header.Spacer />
-          <Header.Actions>
-            <ThemeToggle />
-          </Header.Actions>
-        </Header>
-      </AppShell.Header>
-
-      <AppShell.Sidebar width="240px" collapsible="offcanvas">
-        <Sidebar.Nav>
-          <Sidebar.Section label="Menu">
-            <Sidebar.Item icon={<HomeIcon />} href="/" active>
-              Home
-            </Sidebar.Item>
-            <Sidebar.Item icon={<ChartIcon />} href="/analytics">
-              Analytics
-            </Sidebar.Item>
-            <Sidebar.Item icon={<GearIcon />} href="/settings">
-              Settings
-            </Sidebar.Item>
-          </Sidebar.Section>
-        </Sidebar.Nav>
-      </AppShell.Sidebar>
-
-      <AppShell.Main padding="lg">
-        {children}
-      </AppShell.Main>
-    </AppShell>
-  );
-}
-
-// App Shell - Sidebar Inset Layout (sidebar is full height)
-// Best for documentation sites or when sidebar branding is preferred
-
-function SidebarInsetLayout({ children }) {
-  return (
-    <AppShell layout="sidebar-inset">
-      <AppShell.Header>
-        <Header>
-          <Header.SkipLink />
-          <Header.Trigger />
-          <Header.Search>
-            <Input placeholder="Search..." />
-          </Header.Search>
-          <Header.Spacer />
-          <Header.Actions>
-            <ThemeToggle />
-          </Header.Actions>
-        </Header>
-      </AppShell.Header>
-
-      <AppShell.Sidebar width="260px" collapsible="offcanvas">
-        <Sidebar.Header>
-          <a href="/">MyApp</a>
-        </Sidebar.Header>
-        <Sidebar.Nav>
-          <Sidebar.Section label="Getting Started">
-            <Sidebar.Item href="/docs" active>Introduction</Sidebar.Item>
-            <Sidebar.Item href="/docs/install">Installation</Sidebar.Item>
-          </Sidebar.Section>
-          <Sidebar.Section label="Components">
-            <Sidebar.Item href="/components">Overview</Sidebar.Item>
-            <Sidebar.Item href="/components/button">Button</Sidebar.Item>
-          </Sidebar.Section>
-        </Sidebar.Nav>
-        <Sidebar.Footer>v1.0.0</Sidebar.Footer>
-      </AppShell.Sidebar>
-
-      <AppShell.Main padding="lg">
-        {children}
-      </AppShell.Main>
-    </AppShell>
-  );
-}
-
-// App Shell with Collapsible Icon Sidebar
-// Sidebar collapses to icons only - great for dashboards
-
-function CollapsibleLayout({ children }) {
-  return (
-    <AppShell layout="sidebar-inset">
-      <AppShell.Header>
-        <Header>
-          <Header.Trigger />
-          <Header.Spacer />
-          <Header.Actions>
-            <ThemeToggle />
-          </Header.Actions>
-        </Header>
-      </AppShell.Header>
-
-      <AppShell.Sidebar collapsible="icon" width="240px" collapsedWidth="64px">
-        <Sidebar.Header collapsedContent={<Logo />}>
-          <Logo /> <span>MyApp</span>
-        </Sidebar.Header>
-        <Sidebar.Nav>
-          <Sidebar.Section>
-            <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>
-            <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>
-            <Sidebar.Item icon={<GearIcon />}>Settings</Sidebar.Item>
-          </Sidebar.Section>
-        </Sidebar.Nav>
-        <Sidebar.Footer>
-          <Sidebar.CollapseToggle />
-        </Sidebar.Footer>
-      </AppShell.Sidebar>
-
-      <AppShell.Main padding="lg">
-        {children}
-      </AppShell.Main>
-    </AppShell>
-  );
-}
-
-// App Shell with Aside Panel
-// Optional right panel for additional context
-
-function LayoutWithAside({ children, aside }) {
-  return (
-    <AppShell layout="stacked">
-      <AppShell.Header>
-        <Header>
-          <Header.Brand>MyApp</Header.Brand>
-          <Header.Spacer />
-          <Header.Actions>
-            <ThemeToggle />
-          </Header.Actions>
-        </Header>
-      </AppShell.Header>
-
-      <AppShell.Sidebar width="200px" collapsible="offcanvas">
-        <Sidebar.Nav>
-          <Sidebar.Section>
-            <Sidebar.Item icon={<HomeIcon />} active>Home</Sidebar.Item>
-          </Sidebar.Section>
-        </Sidebar.Nav>
-      </AppShell.Sidebar>
-
-      <AppShell.Main padding="lg">
-        {children}
-      </AppShell.Main>
-
-      <AppShell.Aside width="280px">
-        {aside}
-      </AppShell.Aside>
-    </AppShell>
-  );
-}
-`.trim(),
-});