@fragments-sdk/ui 0.2.3 → 0.4.0

package/src/components/AppShell/index.tsx

@@ -0,0 +1,398 @@
+'use client';
+
+import * as React from 'react';
+import styles from './AppShell.module.scss';
+import {
+  SidebarProvider,
+  Sidebar,
+  useSidebar,
+  type SidebarCollapsible,
+} from '../Sidebar';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type AppShellLayout = 'stacked' | 'sidebar-inset' | 'inset';
+
+export interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /**
+   * Layout mode:
+   * - 'stacked': Header spans full width above sidebar (default)
+   * - 'sidebar-inset': Sidebar is full height, header sits next to it
+   */
+  layout?: AppShellLayout;
+}
+
+export interface AppShellHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Header height (default: '56px') */
+  height?: string;
+}
+
+export interface AppShellSidebarProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Width of expanded sidebar (default: '240px') */
+  width?: string;
+  /** Width when collapsed (default: '64px') */
+  collapsedWidth?: string;
+  /** Collapse behavior */
+  collapsible?: SidebarCollapsible;
+  /** Sidebar position */
+  position?: 'left' | 'right';
+  /** Default collapsed state */
+  defaultCollapsed?: boolean;
+}
+
+export interface AppShellMainProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+  /** Content padding */
+  padding?: 'none' | 'sm' | 'md' | 'lg';
+}
+
+export interface AppShellAsideProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+  /** Aside width (default: '280px') */
+  width?: string;
+  /** Control visibility */
+  visible?: boolean;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface AppShellContextValue {
+  layout: AppShellLayout;
+  headerHeight: string;
+  sidebarWidth: string;
+  sidebarCollapsedWidth: string;
+  asideWidth: string;
+  asideVisible: boolean;
+}
+
+const AppShellContext = React.createContext<AppShellContextValue>({
+  layout: 'stacked',
+  headerHeight: '56px',
+  sidebarWidth: '240px',
+  sidebarCollapsedWidth: '64px',
+  asideWidth: '280px',
+  asideVisible: false,
+});
+
+function useAppShell() {
+  return React.useContext(AppShellContext);
+}
+
+// ============================================
+// Hooks
+// ============================================
+
+function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState(false);
+
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const mq = window.matchMedia('(max-width: 767px)');
+    setIsMobile(mq.matches);
+
+    const handler = (e: MediaQueryListEvent) => setIsMobile(e.matches);
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+
+  return isMobile;
+}
+
+// ============================================
+// Helper to extract config from children
+// ============================================
+
+interface ExtractedConfig {
+  headerHeight: string;
+  sidebarWidth: string;
+  sidebarCollapsedWidth: string;
+  sidebarCollapsible: SidebarCollapsible;
+  sidebarDefaultCollapsed: boolean;
+  asideWidth: string;
+  asideVisible: boolean;
+}
+
+function extractConfigFromChildren(children: React.ReactNode): ExtractedConfig {
+  const config: ExtractedConfig = {
+    headerHeight: '56px',
+    sidebarWidth: '240px',
+    sidebarCollapsedWidth: '64px',
+    sidebarCollapsible: 'icon',
+    sidebarDefaultCollapsed: false,
+    asideWidth: '280px',
+    asideVisible: false,
+  };
+
+  React.Children.forEach(children, child => {
+    if (!React.isValidElement(child)) return;
+
+    if (child.type === AppShellHeader) {
+      const props = child.props as AppShellHeaderProps;
+      if (props.height) config.headerHeight = props.height;
+    }
+
+    if (child.type === AppShellSidebar) {
+      const props = child.props as AppShellSidebarProps;
+      if (props.width) config.sidebarWidth = props.width;
+      if (props.collapsedWidth) config.sidebarCollapsedWidth = props.collapsedWidth;
+      if (props.collapsible) config.sidebarCollapsible = props.collapsible;
+      if (props.defaultCollapsed !== undefined) config.sidebarDefaultCollapsed = props.defaultCollapsed;
+    }
+
+    if (child.type === AppShellAside) {
+      const props = child.props as AppShellAsideProps;
+      if (props.width) config.asideWidth = props.width;
+      if (props.visible !== false) config.asideVisible = true;
+    }
+  });
+
+  return config;
+}
+
+// ============================================
+// Internal component to apply CSS variables
+// ============================================
+
+function AppShellInner({
+  children,
+  className,
+  layout,
+  ...htmlProps
+}: {
+  children: React.ReactNode;
+  className?: string;
+  layout: AppShellLayout;
+} & React.HTMLAttributes<HTMLDivElement>) {
+  const appShell = useAppShell();
+  const { collapsed, isMobile, collapsible } = useSidebar();
+
+  const classes = [
+    styles.root,
+    (layout === 'sidebar-inset' || layout === 'inset') && styles.sidebarInset,
+    layout === 'inset' && styles.insetLayout,
+    className,
+  ].filter(Boolean).join(' ');
+
+  // Calculate actual sidebar width based on state
+  const actualSidebarWidth = isMobile
+    ? '0px'
+    : (collapsible === 'icon' && collapsed)
+      ? appShell.sidebarCollapsedWidth
+      : (collapsible === 'offcanvas' && collapsed)
+        ? '0px'
+        : appShell.sidebarWidth;
+
+  const style: React.CSSProperties = {
+    '--appshell-header-height': appShell.headerHeight,
+    '--appshell-sidebar-width': actualSidebarWidth,
+    '--appshell-sidebar-expanded-width': appShell.sidebarWidth,
+    '--appshell-sidebar-collapsed-width': appShell.sidebarCollapsedWidth,
+    '--appshell-aside-width': appShell.asideVisible ? appShell.asideWidth : '0px',
+  } as React.CSSProperties;
+
+  return (
+    <div {...htmlProps} className={classes} style={style} data-layout={layout} data-mobile={isMobile || undefined}>
+      {children}
+    </div>
+  );
+}
+
+// ============================================
+// Components
+// ============================================
+
+/**
+ * AppShell - Root layout wrapper
+ * Automatically wraps children with SidebarProvider
+ */
+function AppShellRoot({
+  children,
+  layout = 'stacked',
+  className,
+  ...htmlProps
+}: AppShellProps) {
+  // Extract config from children using useMemo to avoid re-renders
+  const config = React.useMemo(() => extractConfigFromChildren(children), [children]);
+
+  const contextValue: AppShellContextValue = {
+    layout,
+    headerHeight: config.headerHeight,
+    sidebarWidth: config.sidebarWidth,
+    sidebarCollapsedWidth: config.sidebarCollapsedWidth,
+    asideWidth: config.asideWidth,
+    asideVisible: config.asideVisible,
+  };
+
+  return (
+    <AppShellContext.Provider value={contextValue}>
+      <SidebarProvider
+        width={config.sidebarWidth}
+        collapsedWidth={config.sidebarCollapsedWidth}
+        collapsible={config.sidebarCollapsible}
+        defaultCollapsed={config.sidebarDefaultCollapsed}
+      >
+        <AppShellInner className={className} layout={layout} {...htmlProps}>
+          {children}
+        </AppShellInner>
+      </SidebarProvider>
+    </AppShellContext.Provider>
+  );
+}
+
+/**
+ * AppShell.Header - Fixed header slot
+ */
+function AppShellHeader({
+  children,
+  height = '56px',
+  className,
+  style: styleProp,
+  ...htmlProps
+}: AppShellHeaderProps) {
+  const { layout } = useAppShell();
+
+  const classes = [
+    styles.header,
+    (layout === 'sidebar-inset' || layout === 'inset') && styles.headerInset,
+    layout === 'inset' && styles.headerInsetRounded,
+    className,
+  ].filter(Boolean).join(' ');
+
+  const style: React.CSSProperties = {
+    '--header-height': height,
+    ...styleProp,
+  } as React.CSSProperties;
+
+  return (
+    <div {...htmlProps} className={classes} style={style}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * AppShell.Sidebar - Sidebar slot (delegates to Sidebar component)
+ */
+function AppShellSidebar({
+  children,
+  width = '240px',
+  collapsedWidth = '64px',
+  collapsible = 'icon',
+  position = 'left',
+  defaultCollapsed = false,
+  className,
+  ...htmlProps
+}: AppShellSidebarProps) {
+  const isMobile = useIsMobile();
+  const { layout } = useAppShell();
+
+  const classes = [
+    styles.sidebar,
+    (layout === 'sidebar-inset' || layout === 'inset') && styles.sidebarFullHeight,
+    layout === 'inset' && styles.sidebarInsetRounded,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <div {...htmlProps} className={classes}>
+      <Sidebar
+        width={width}
+        collapsedWidth={collapsedWidth}
+        position={position}
+        collapsible={collapsible}
+        defaultCollapsed={defaultCollapsed}
+      >
+        {children}
+      </Sidebar>
+      {isMobile && <Sidebar.Overlay />}
+    </div>
+  );
+}
+
+/**
+ * AppShell.Main - Scrollable main content area
+ */
+function AppShellMain({
+  children,
+  padding = 'md',
+  className,
+  id = 'main-content',
+  ...htmlProps
+}: AppShellMainProps) {
+  const { layout } = useAppShell();
+
+  const classes = [
+    styles.main,
+    padding !== 'none' && styles[`padding${padding.charAt(0).toUpperCase() + padding.slice(1)}`],
+    layout === 'inset' && styles.mainInset,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <main {...htmlProps} className={classes} id={id}>
+      {children}
+    </main>
+  );
+}
+
+/**
+ * AppShell.Aside - Optional right sidebar panel
+ */
+function AppShellAside({
+  children,
+  width = '280px',
+  visible = true,
+  className,
+  style: styleProp,
+  ...htmlProps
+}: AppShellAsideProps) {
+  const isMobile = useIsMobile();
+
+  // Hide aside on mobile
+  if (isMobile || !visible) {
+    return null;
+  }
+
+  const classes = [styles.aside, className].filter(Boolean).join(' ');
+
+  const style: React.CSSProperties = {
+    '--aside-width': width,
+    ...styleProp,
+  } as React.CSSProperties;
+
+  return (
+    <aside {...htmlProps} className={classes} style={style}>
+      {children}
+    </aside>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const AppShell = Object.assign(AppShellRoot, {
+  Header: AppShellHeader,
+  Sidebar: AppShellSidebar,
+  Main: AppShellMain,
+  Aside: AppShellAside,
+});
+
+export {
+  AppShellRoot,
+  AppShellHeader,
+  AppShellSidebar,
+  AppShellMain,
+  AppShellAside,
+  useAppShell,
+};

package/src/components/Avatar/index.tsx

@@ -9,7 +9,7 @@ import '../../styles/globals.scss';
 
 export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 
-export interface AvatarProps {
+export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'> {
   /** Image source URL */
   src?: string;
   /** Alt text for the image */
@@ -24,19 +24,15 @@ export interface AvatarProps {
   shape?: 'circle' | 'square';
   /** Custom background color for fallback */
   color?: string;
-  /** Additional class name */
-  className?: string;
 }
 
-export interface AvatarGroupProps {
+export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Maximum number of avatars to display */
   max?: number;
   /** Size for all avatars in the group */
   size?: AvatarSize;
   /** Children (Avatar components) */
   children: React.ReactNode;
-  /** Additional class name */
-  className?: string;
 }
 
 // ============================================
@@ -76,6 +72,8 @@ const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
       shape = 'circle',
       color,
       className,
+      style: styleProp,
+      ...htmlProps
     },
     ref
   ) {
@@ -97,13 +95,13 @@ const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
       className,
     ].filter(Boolean).join(' ');
 
-    const style: React.CSSProperties = {};
+    const style: React.CSSProperties = { ...styleProp };
     if (showFallback && fallbackColor) {
       style.backgroundColor = fallbackColor;
     }
 
     return (
-      <div ref={ref} className={avatarClasses} style={style}>
+      <div ref={ref} {...htmlProps} className={avatarClasses} style={style}>
         {!showFallback && (
           <img
             src={src}
@@ -140,6 +138,7 @@ function AvatarGroup({
   size = 'md',
   children,
   className,
+  ...htmlProps
 }: AvatarGroupProps) {
   const childArray = React.Children.toArray(children);
   const displayCount = max && max < childArray.length ? max : childArray.length;
@@ -148,7 +147,7 @@ function AvatarGroup({
   const groupClasses = [styles.group, className].filter(Boolean).join(' ');
 
   return (
-    <div className={groupClasses}>
+    <div {...htmlProps} className={groupClasses}>
       {childArray.slice(0, displayCount).map((child, index) => {
         if (React.isValidElement<AvatarProps>(child)) {
           return React.cloneElement(child, {

package/src/components/Badge/Badge.module.scss

@@ -14,12 +14,12 @@
 
 // Sizes
 .sm {
-  padding: 2px var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-0-5, $fui-space-0-5) var(--fui-space-2, $fui-space-2);
   font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
 }
 
 .md {
-  padding: var(--fui-space-1, $fui-space-1) 10px;
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1);
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
 }
 
@@ -49,15 +49,21 @@
   color: var(--fui-color-info, $fui-color-info);
 }
 
+.outline {
+  background-color: transparent;
+  color: var(--fui-text-primary, $fui-text-primary);
+  border: 1px solid var(--fui-border-strong, $fui-border-strong);
+}
+
 .dot {
-  width: 6px;
-  height: 6px;
+  width: $fui-badge-dot-md;
+  height: $fui-badge-dot-md;
   border-radius: 50%;
   background-color: currentColor;
 
   .sm & {
-    width: 5px;
-    height: 5px;
+    width: $fui-badge-dot-sm;
+    height: $fui-badge-dot-sm;
   }
 }
 
@@ -70,15 +76,15 @@
   @include button-reset;
   @include interactive-base;
 
-  padding: 0 2px;
-  font-size: 14px;
+  padding: 0 var(--fui-space-0-5, $fui-space-0-5);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
   color: inherit;
   opacity: 0.6;
   line-height: 1;
-  border-radius: 2px;
+  border-radius: var(--fui-space-0-5, $fui-space-0-5);
 
   .sm & {
-    font-size: 12px;
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   }
 
   &:hover {

package/src/components/Badge/index.tsx

@@ -4,14 +4,13 @@ import styles from './Badge.module.scss';
 // Import globals to ensure CSS variables are defined
 import '../../styles/globals.scss';
 
-export interface BadgeProps {
+export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
   children: React.ReactNode;
-  variant?: 'default' | 'success' | 'warning' | 'error' | 'info';
+  variant?: 'default' | 'success' | 'warning' | 'error' | 'info' | 'outline';
   size?: 'sm' | 'md';
   dot?: boolean;
   icon?: React.ReactNode;
   onRemove?: () => void;
-  className?: string;
 }
 
 export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
@@ -24,6 +23,8 @@ export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
       icon,
       onRemove,
       className,
+      'aria-label': ariaLabel,
+      ...htmlProps
     },
     ref
   ) {
@@ -31,19 +32,32 @@ export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
       .filter(Boolean)
       .join(' ');
 
+    // For status badges, include the status in the aria-label if not provided
+    const effectiveAriaLabel = ariaLabel || (
+      variant !== 'default' && variant !== 'outline'
+        ? `${variant}: ${typeof children === 'string' ? children : ''}`
+        : undefined
+    );
+
     return (
-      <span ref={ref} className={classes}>
+      <span
+        ref={ref}
+        {...htmlProps}
+        className={classes}
+        role={effectiveAriaLabel ? 'status' : undefined}
+        aria-label={effectiveAriaLabel}
+      >
         {dot && <span className={styles.dot} aria-hidden="true" />}
         {icon && (
           <span className={styles.icon} aria-hidden="true">
             {icon}
           </span>
         )}
-        {children}
+        <span>{children}</span>
         {onRemove && (
           <BaseButton
             onClick={onRemove}
-            aria-label="Remove"
+            aria-label={`Remove ${typeof children === 'string' ? children : 'badge'}`}
             className={styles.remove}
           >
             &times;