@fragments-sdk/ui 0.15.1 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -230,7 +230,7 @@
     "vite": "^6.0.0",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@fragments-sdk/core": "0.3.0"
+    "@fragments-sdk/core": "1.0.0"
   },
   "files": [
     "src",

package/src/components/AppShell/AppShell.module.scss

@@ -6,9 +6,8 @@
 // ============================================
 // Grid areas: header, sidebar, main, aside
 //
-// 'default':           header spans full width, sidebar below
-// 'sidebar':           sidebar spans full height, header beside it
-// 'sidebar-floating':  like sidebar, but main floats with rounded corners
+// Structure is controlled by the `layout` prop ('default' | 'sidebar').
+// Visual treatment (floating) is controlled per-slot via `variant` props.
 
 .root {
   display: grid;
@@ -48,7 +47,7 @@
   }
 }
 
-// Sidebar layout: sidebar spans full height
+// Sidebar structure: sidebar spans full height
 // sidebar header header
 // sidebar main   aside
 .sidebarLayout {
@@ -65,11 +64,6 @@
   }
 }
 
-// Sidebar-floating layout: shell background frames the floating main area
-.sidebarFloatingLayout {
-  background-color: var(--fui-bg-primary, $fui-bg-primary);
-}
-
 // ============================================
 // Header
 // ============================================
@@ -83,11 +77,6 @@
   background-color: var(--fui-bg-primary, $fui-bg-primary);
 }
 
-// Header in sidebar-floating layout — matches shell bg
-.headerFloating {
-  background-color: var(--fui-bg-primary, $fui-bg-primary);
-}
-
 // ============================================
 // Sidebar
 // ============================================
@@ -129,7 +118,7 @@
   }
 }
 
-// Sidebar in sidebar/sidebar-floating layouts: full height
+// Sidebar in sidebar structure: full height
 .sidebarFullHeight {
   top: 0;
   height: 100vh;
@@ -141,11 +130,9 @@
   }
 }
 
-// Sidebar in sidebar-floating layout: no borders, primary bg (matches shell)
+// Sidebar variant="floating": blends with shell background (bg applied via inline style on Sidebar)
 .sidebarFloating {
-  :global(.root) {
-    background-color: var(--fui-bg-primary, $fui-bg-primary);
-  }
+  // No additional styles needed — bg prop is passed directly to the Sidebar component
 }
 
 // ============================================
@@ -159,13 +146,15 @@
   background-color: var(--fui-bg-primary, $fui-bg-primary);
 }
 
-// Main content in sidebar-floating layout — elevated card effect
+// Main variant="floating": elevated card effect with inset from edges
 .mainFloating {
+  margin: var(--fui-space-2, $fui-space-2) var(--fui-space-2, $fui-space-2) var(--fui-space-2, $fui-space-2) 0;
   border-radius: var(--fui-radius-xl, $fui-radius-xl);
   background-color: var(--fui-bg-secondary, $fui-bg-secondary);
   overflow: hidden;
 
   @include below-md {
+    margin: var(--fui-space-2, $fui-space-2) 0;
     border-radius: var(--fui-radius-lg, $fui-radius-lg);
     width: 100%;
   }
@@ -216,3 +205,23 @@
     border-top: 1px solid var(--fui-border, $fui-border);
   }
 }
+
+// Aside variant="floating": elevated card effect with inset from edges
+.asideFloating {
+  // Override the explicit width so the aside fills its grid cell
+  // and the margin creates visible inset space from the viewport edge.
+  width: auto;
+  height: calc(100vh - var(--appshell-header-height, 56px) - var(--fui-space-2, $fui-space-2) * 2);
+  height: calc(100dvh - var(--appshell-header-height, 56px) - var(--fui-space-2, $fui-space-2) * 2);
+  margin: var(--fui-space-2, $fui-space-2) var(--fui-space-2, $fui-space-2) var(--fui-space-2, $fui-space-2) 0;
+  border-radius: var(--fui-radius-xl, $fui-radius-xl);
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  overflow: hidden;
+
+  @include below-md {
+    margin: var(--fui-space-2, $fui-space-2) 0;
+    border-radius: var(--fui-radius-lg, $fui-radius-lg);
+    width: 100%;
+    height: auto;
+  }
+}

package/src/components/AppShell/index.tsx

@@ -14,46 +14,62 @@ import {
 // ============================================
 
 /**
+ * Structural layout — controls CSS grid areas.
+ *
  * ```
- * 'default'           'sidebar'          'sidebar-floating'
- * ┌──────────────┐    ┌────┬─────────┐   ┌────┬─────────┐
- * │    Header    │    │    │ Header  │   │    │ Header  │
- * ├────┬─────────┤    │Side├─────────┤   │Side├╌╌╌╌╌╌╌╌╌┤
- * │    │         │    │bar │         │   │bar │┌───────┐│
- * │Side│  Main   │    │    │  Main   │   │    ││ Main  ││
- * │bar │         │    │    │         │   │    │└───────┘│
- * └────┴─────────┘    └────┴─────────┘   └────┴─────────┘
+ * 'default'           'sidebar'
+ * ┌──────────────┐    ┌────┬─────────┐
+ * │    Header    │    │    │ Header  │
+ * ├────┬─────────┤    │Side├─────────┤
+ * │    │         │    │bar │         │
+ * │Side│  Main   │    │    │  Main   │
+ * │bar │         │    │    │         │
+ * └────┴─────────┘    └────┴─────────┘
  * ```
+ *
+ * Combine with `variant="floating"` on individual slots for floating effects:
+ *
+ * ```tsx
+ * <AppShell layout="sidebar">
+ *   <AppShell.Sidebar variant="floating" />
+ *   <AppShell.Main variant="floating" />
+ *   <AppShell.Aside variant="floating" />
+ * </AppShell>
+ * ```
+ *
+ * Legacy values `'sidebar-floating'` and `'floating'` are still accepted
+ * for backwards compatibility and internally expand to the appropriate
+ * per-slot variants.
  */
-export type AppShellLayout = 'default' | 'sidebar' | 'sidebar-floating';
+export type AppShellLayout = 'default' | 'sidebar' | 'sidebar-floating' | 'floating';
+
+/** Visual treatment for individual layout slots. */
+export type AppShellSlotVariant = 'default' | 'floating';
 
 export interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
   /**
-   * Layout mode:
-   *
-   * ```
-   * 'default'           'sidebar'          'sidebar-floating'
-   * ┌──────────────┐    ┌────┬─────────┐   ┌────┬─────────┐
-   * │    Header    │    │    │ Header  │   │    │ Header  │
-   * ├────┬─────────┤    │Side├─────────┤   │Side├╌╌╌╌╌╌╌╌╌┤
-   * │    │         │    │bar │         │   │bar │┌───────┐│
-   * │Side│  Main   │    │    │  Main   │   │    ││ Main  ││
-   * │bar │         │    │    │         │   │    │└───────┘│
-   * └────┴─────────┘    └────┴─────────┘   └────┴─────────┘
-   * ```
+   * Layout structure:
    *
    * - `'default'`: Header spans full width, sidebar below (default)
    * - `'sidebar'`: Sidebar is full height, header sits beside it
-   * - `'sidebar-floating'`: Like `sidebar` but main content floats with rounded corners and a distinct background
+   *
+   * Legacy presets (still work, prefer per-slot `variant` props instead):
+   *
+   * - `'sidebar-floating'`: Expands to `layout="sidebar"` with floating sidebar + main
+   * - `'floating'`: Expands to `layout="sidebar"` with floating sidebar + main + aside
    */
   layout?: AppShellLayout;
+  /** Background color for the shell container (accepts any CSS color value or token) */
+  bg?: string;
 }
 
 export interface AppShellHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
   /** Header height (default: '56px') */
   height?: string;
+  /** Background color override (accepts any CSS color value or token) */
+  bg?: string;
 }
 
 export interface AppShellSidebarProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -68,12 +84,20 @@ export interface AppShellSidebarProps extends React.HTMLAttributes<HTMLDivElemen
   position?: 'left' | 'right';
   /** Default collapsed state */
   defaultCollapsed?: boolean;
+  /** Visual treatment: `'floating'` blends sidebar with the shell background */
+  variant?: AppShellSlotVariant;
+  /** Background color override (accepts any CSS color value or token) */
+  bg?: string;
 }
 
 export interface AppShellMainProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** Content padding */
   padding?: 'none' | 'sm' | 'md' | 'lg';
+  /** Visual treatment: `'floating'` adds rounded corners and elevated background */
+  variant?: AppShellSlotVariant;
+  /** Background color override (accepts any CSS color value or token) */
+  bg?: string;
 }
 
 export interface AppShellAsideProps extends React.HTMLAttributes<HTMLElement> {
@@ -82,6 +106,35 @@ export interface AppShellAsideProps extends React.HTMLAttributes<HTMLElement> {
   width?: string;
   /** Control visibility */
   visible?: boolean;
+  /** Visual treatment: `'floating'` adds rounded corners and elevated background */
+  variant?: AppShellSlotVariant;
+  /** Background color override (accepts any CSS color value or token) */
+  bg?: string;
+}
+
+// ============================================
+// Layout resolution helpers
+// ============================================
+
+/** Resolve a layout value to its structural grid mode. */
+function resolveStructure(layout: AppShellLayout): 'default' | 'sidebar' {
+  if (layout === 'sidebar' || layout === 'sidebar-floating' || layout === 'floating') return 'sidebar';
+  return 'default';
+}
+
+/**
+ * Resolve a slot's visual variant.
+ * Explicit `variant` prop always wins. Otherwise, infer from legacy layout values.
+ */
+function resolveSlotVariant(
+  explicit: AppShellSlotVariant | undefined,
+  layout: AppShellLayout,
+  slot: 'main' | 'aside' | 'sidebar',
+): AppShellSlotVariant {
+  if (explicit !== undefined) return explicit;
+  if ((layout === 'sidebar-floating' || layout === 'floating') && (slot === 'main' || slot === 'sidebar')) return 'floating';
+  if (layout === 'floating' && slot === 'aside') return 'floating';
+  return 'default';
 }
 
 // ============================================
@@ -90,6 +143,7 @@ export interface AppShellAsideProps extends React.HTMLAttributes<HTMLElement> {
 
 interface AppShellContextValue {
   layout: AppShellLayout;
+  structure: 'default' | 'sidebar';
   headerHeight: string;
   sidebarWidth: string;
   sidebarCollapsedWidth: string;
@@ -99,6 +153,7 @@ interface AppShellContextValue {
 
 const AppShellContext = React.createContext<AppShellContextValue>({
   layout: 'default',
+  structure: 'default',
   headerHeight: '56px',
   sidebarWidth: '240px',
   sidebarCollapsedWidth: '64px',
@@ -190,20 +245,21 @@ function AppShellInner({
   children,
   className,
   layout,
+  structure,
   style: styleProp,
   ...htmlProps
 }: {
   children: React.ReactNode;
   className?: string;
   layout: AppShellLayout;
+  structure: 'default' | 'sidebar';
 } & React.HTMLAttributes<HTMLDivElement>) {
   const appShell = useAppShell();
   const { collapsed, isMobile, collapsible } = useSidebar();
 
   const classes = [
     styles.root,
-    (layout === 'sidebar' || layout === 'sidebar-floating') && styles.sidebarLayout,
-    layout === 'sidebar-floating' && styles.sidebarFloatingLayout,
+    structure === 'sidebar' && styles.sidebarLayout,
     className,
   ].filter(Boolean).join(' ');
 
@@ -243,14 +299,19 @@ function AppShellInner({
 function AppShellRoot({
   children,
   layout = 'default',
+  bg,
   className,
+  style: styleProp,
   ...htmlProps
 }: AppShellProps) {
+  const structure = resolveStructure(layout);
+
   // Extract config from children using useMemo to avoid re-renders
   const config = React.useMemo(() => extractConfigFromChildren(children), [children]);
 
   const contextValue: AppShellContextValue = {
     layout,
+    structure,
     headerHeight: config.headerHeight,
     sidebarWidth: config.sidebarWidth,
     sidebarCollapsedWidth: config.sidebarCollapsedWidth,
@@ -266,7 +327,7 @@ function AppShellRoot({
         collapsible={config.sidebarCollapsible}
         defaultCollapsed={config.sidebarDefaultCollapsed}
       >
-        <AppShellInner className={className} layout={layout} {...htmlProps}>
+        <AppShellInner className={className} layout={layout} structure={structure} style={{ ...(bg ? { backgroundColor: bg } : {}), ...styleProp }} {...htmlProps}>
           {children}
         </AppShellInner>
       </SidebarProvider>
@@ -280,21 +341,19 @@ function AppShellRoot({
 function AppShellHeader({
   children,
   height = '56px',
+  bg,
   className,
   style: styleProp,
   ...htmlProps
 }: AppShellHeaderProps) {
-  const { layout } = useAppShell();
-
   const classes = [
     styles.header,
-    (layout === 'sidebar' || layout === 'sidebar-floating') && styles.headerSidebar,
-    layout === 'sidebar-floating' && styles.headerFloating,
     className,
   ].filter(Boolean).join(' ');
 
   const style: React.CSSProperties = {
     '--header-height': height,
+    ...(bg ? { backgroundColor: bg } : {}),
     ...styleProp,
   } as React.CSSProperties;
 
@@ -315,22 +374,30 @@ function AppShellSidebar({
   collapsible = 'icon',
   position = 'left',
   defaultCollapsed = false,
+  variant,
+  bg,
   'aria-label': ariaLabel,
   className,
+  style: styleProp,
   ...htmlProps
 }: AppShellSidebarProps) {
   const isMobile = useIsMobile();
-  const { layout } = useAppShell();
+  const { layout, structure } = useAppShell();
+  const resolvedVariant = resolveSlotVariant(variant, layout, 'sidebar');
 
   const classes = [
     styles.sidebar,
-    (layout === 'sidebar' || layout === 'sidebar-floating') && styles.sidebarFullHeight,
-    layout === 'sidebar-floating' && styles.sidebarFloating,
+    structure === 'sidebar' && styles.sidebarFullHeight,
+    resolvedVariant === 'floating' && styles.sidebarFloating,
     className,
   ].filter(Boolean).join(' ');
 
+  const style: React.CSSProperties = {
+    ...styleProp,
+  } as React.CSSProperties;
+
   return (
-    <div {...htmlProps} className={classes}>
+    <div {...htmlProps} className={classes} style={style}>
       <Sidebar
         width={width}
         collapsedWidth={collapsedWidth}
@@ -338,6 +405,7 @@ function AppShellSidebar({
         collapsible={collapsible}
         defaultCollapsed={defaultCollapsed}
         aria-label={ariaLabel}
+        style={bg ? { backgroundColor: bg } : undefined}
       >
         {children}
       </Sidebar>
@@ -352,21 +420,30 @@ function AppShellSidebar({
 function AppShellMain({
   children,
   padding = 'md',
+  variant,
+  bg,
   className,
+  style: styleProp,
   id = 'main-content',
   ...htmlProps
 }: AppShellMainProps) {
   const { layout } = useAppShell();
+  const resolvedVariant = resolveSlotVariant(variant, layout, 'main');
 
   const classes = [
     styles.main,
     padding !== 'none' && styles[`padding${padding.charAt(0).toUpperCase() + padding.slice(1)}`],
-    layout === 'sidebar-floating' && styles.mainFloating,
+    resolvedVariant === 'floating' && styles.mainFloating,
     className,
   ].filter(Boolean).join(' ');
 
+  const style: React.CSSProperties = {
+    ...(bg ? { backgroundColor: bg } : {}),
+    ...styleProp,
+  } as React.CSSProperties;
+
   return (
-    <main {...htmlProps} className={classes} id={id}>
+    <main {...htmlProps} className={classes} style={style} id={id}>
       {children}
     </main>
   );
@@ -379,18 +456,28 @@ function AppShellAside({
   children,
   width = '280px',
   visible = true,
+  variant,
+  bg,
   className,
   style: styleProp,
   ...htmlProps
 }: AppShellAsideProps) {
+  const { layout } = useAppShell();
+  const resolvedVariant = resolveSlotVariant(variant, layout, 'aside');
+
   if (!visible) {
     return null;
   }
 
-  const classes = [styles.aside, className].filter(Boolean).join(' ');
+  const classes = [
+    styles.aside,
+    resolvedVariant === 'floating' && styles.asideFloating,
+    className,
+  ].filter(Boolean).join(' ');
 
   const style: React.CSSProperties = {
     '--aside-width': width,
+    ...(bg ? { backgroundColor: bg } : {}),
     ...styleProp,
   } as React.CSSProperties;
 

package/src/components/CodeBlock/index.tsx

@@ -28,7 +28,6 @@ async function loadShikiDeps() {
   await _shikiLoadPromise;
 }
 import { TabsRoot, TabsList, Tab, TabsPanel } from "../Tabs";
-import { Button } from "../Button";
 import styles from "./CodeBlock.module.scss";
 import "../../styles/globals.scss";
 

package/src/components/DatePicker/index.tsx

@@ -2,7 +2,7 @@
 
 import * as React from 'react';
 import { Popover as BasePopover } from '@base-ui/react/popover';
-import { mergeAriaIds, useFormFieldIds, type FormFieldProps } from '../../utils/aria';
+import { useFormFieldIds, type FormFieldProps } from '../../utils/aria';
 import styles from './DatePicker.module.scss';
 // Import globals to ensure CSS variables are defined
 import '../../styles/globals.scss';

package/src/components/Form/index.tsx

@@ -28,7 +28,7 @@ function FormRoot({
   errors,
   onSubmit,
   onFormSubmit,
-  onClearErrors,
+  onClearErrors: _onClearErrors,
   validationMode,
   className,
   ...htmlProps

package/src/components/Menu/index.tsx

@@ -73,7 +73,7 @@ export interface MenuGroupLabelProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
 }
 
-export interface MenuSeparatorProps extends React.HTMLAttributes<HTMLElement> {}
+export type MenuSeparatorProps = React.HTMLAttributes<HTMLElement>;
 
 export interface MenuSubmenuProps {
   children: React.ReactNode;

package/src/components/NavigationMenu/useNavigationMenu.ts

@@ -64,10 +64,13 @@ export function useNavigationMenu({
 
   // Clean up timers on unmount
   React.useEffect(() => {
+    const openTimer = openTimerRef.current;
+    const closeTimer = closeTimerRef.current;
+    const skipDelayTimer = skipDelayTimerRef.current;
     return () => {
-      if (openTimerRef.current) clearTimeout(openTimerRef.current);
-      if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
-      if (skipDelayTimerRef.current) clearTimeout(skipDelayTimerRef.current);
+      if (openTimer) clearTimeout(openTimer);
+      if (closeTimer) clearTimeout(closeTimer);
+      if (skipDelayTimer) clearTimeout(skipDelayTimer);
     };
   }, []);
 

package/src/index.ts

@@ -341,6 +341,7 @@ export {
   AppShell,
   type AppShellProps,
   type AppShellLayout,
+  type AppShellSlotVariant,
   type AppShellHeaderProps,
   type AppShellSidebarProps,
   type AppShellMainProps,

package/src/utils/seed-derivation.ts

@@ -266,15 +266,6 @@ function rgbToHex(r: number, g: number, b: number): string {
   return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
 }
 
-/**
- * Check if a color is considered "dark" (luminance < 0.5)
- */
-function isDarkColor(hex: string): boolean {
-  const { r, g, b } = hexToRgb(hex);
-  const luminance = 0.2126 * (r / 255) + 0.7152 * (g / 255) + 0.0722 * (b / 255);
-  return luminance < 0.5;
-}
-
 /**
  * Lighten a color by a percentage
  */

package/src/utils/theme-presets.ts

@@ -8,7 +8,6 @@
 
 import {
   type SeedConfig,
-  type NeutralPalette,
   PALETTES,
   RADIUS_STYLES,
   getSemanticColors,