@fragments-sdk/ui 0.8.0 → 0.8.2

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { ToggleGroup } from '.';
 
 function DefaultExample() {
@@ -92,7 +92,7 @@ function DisabledItemExample() {
   );
 }
 
-export default defineSegment({
+export default defineFragment({
   component: ToggleGroup,
 
   meta: {
@@ -100,7 +100,7 @@ export default defineSegment({
     description: 'A group of toggle buttons where only one can be selected at a time. Useful for switching between views, modes, or options.',
     category: 'forms',
     status: 'stable',
-    tags: ['toggle', 'group', 'segmented', 'control', 'tabs', 'switch'],
+    tags: ['toggle', 'group', 'fragmented', 'control', 'tabs', 'switch'],
     since: '0.2.0',
   },
 
@@ -108,7 +108,7 @@ export default defineSegment({
     when: [
       'Switching between mutually exclusive views or modes',
       'Selecting one option from a small set (2-5 options)',
-      'Segmented controls like view switchers',
+      'Fragmented controls like view switchers',
       'Filter or sort options',
     ],
     whenNot: [
@@ -185,7 +185,7 @@ export default defineSegment({
     scenarioTags: [
       'forms.selection',
       'input.toggle',
-      'control.segmented',
+      'control.fragmented',
     ],
     a11yRules: ['A11Y_GROUP_ROLE', 'A11Y_KEYBOARD_ACCESSIBLE'],
   },
@@ -194,31 +194,63 @@ export default defineSegment({
     {
       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/components/Tooltip/Tooltip.fragment.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { Tooltip } from '.';
 import { Button } from '../Button';
 
-export default defineSegment({
+export default defineFragment({
   component: Tooltip,
 
   meta: {

package/src/components/VisuallyHidden/VisuallyHidden.fragment.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
-import { defineSegment } from '@fragments/core';
+import { defineFragment } from '@fragments/core';
 import { VisuallyHidden } from '.';
 
-export default defineSegment({
+export default defineFragment({
   component: VisuallyHidden,
 
   meta: {

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/tokens/_mixins.scss

@@ -72,6 +72,15 @@
   color: var(--fui-text-secondary, #{$fui-text-secondary});
 }
 
+// Section label text (e.g. sidebar headings, TOC label)
+@mixin section-label-text {
+  @include helper-text;
+  font-size: var(--fui-font-size-2xs, #{$fui-font-size-2xs});
+  font-weight: var(--fui-font-weight-medium, #{$fui-font-weight-medium});
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
 // Card surface
 @mixin surface-elevated {
   background-color: var(--fui-bg-elevated, #{$fui-bg-elevated});

package/src/tokens/_variables.scss

@@ -346,8 +346,8 @@ $fui-theme-toggle-lg-height: 34px !default;
 $fui-theme-toggle-lg-icon: 18px !default;
 
 // CodeBlock (light mode)
-$fui-code-bg: #1e1e1e !default;
-$fui-code-header-bg: #252526 !default;
+$fui-code-bg: var(--fui-bg-elevated) !default;
+$fui-code-header-bg: var(--fui-bg-elevated) !default;
 $fui-code-text: #d4d4d4 !default;
 $fui-code-text-muted: #6b7280 !default;
 $fui-code-border: rgba(255, 255, 255, 0.1) !default;
@@ -372,8 +372,8 @@ $fui-tooltip-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.2), 0 2px 4px -2px rgba(0, 0
 $fui-hero-gradient-color: rgba(120, 119, 198, 0.15) !default;
 
 // CodeBlock (dark mode) - same as light, code blocks stay dark
-$fui-dark-code-bg: #1e1e1e !default;
-$fui-dark-code-header-bg: #252526 !default;
+$fui-dark-code-bg: var(--fui-bg-elevated) !default;
+$fui-dark-code-header-bg: var(--fui-bg-elevated) !default;
 $fui-dark-code-text: #d4d4d4 !default;
 $fui-dark-code-text-muted: #6b7280 !default;
 $fui-dark-code-border: rgba(255, 255, 255, 0.1) !default;

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(),
-});