@syscore/ui-library 1.25.0 → 2.0.0

package/client/components/ui/layout.tsx

@@ -0,0 +1,381 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+// Spacing scale — matches Tailwind (1 unit = 4px)
+const spacing = (n: number): string => `${n * 0.25}rem`;
+
+// ---------------------------------------------------------------------------
+// Stack
+// ---------------------------------------------------------------------------
+type StackDirection = "vertical" | "horizontal";
+type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
+type StackJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
+
+interface StackProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  direction?: StackDirection;
+  gap?: number;
+  align?: StackAlign;
+  justify?: StackJustify;
+  wrap?: boolean;
+}
+
+const Stack = React.forwardRef<HTMLElement, StackProps>(
+  ({ as: Component = "div", direction = "vertical", gap = 4, align, justify, wrap = false, className, style, ...props }, ref) => (
+    <Component
+      ref={ref}
+      className={cn(
+        "stack",
+        direction === "horizontal" && "stack--horizontal",
+        align && `stack--align-${align}`,
+        justify && `stack--justify-${justify}`,
+        wrap && "stack--wrap",
+        className,
+      )}
+      style={{ gap: spacing(gap), ...style }}
+      {...props}
+    />
+  ),
+);
+Stack.displayName = "Stack";
+
+// ---------------------------------------------------------------------------
+// Grid
+// ---------------------------------------------------------------------------
+type GridCols = 1 | 2 | 3 | 4 | 6 | 12;
+
+interface GridProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  cols?: GridCols;
+  colsSm?: GridCols;
+  colsMd?: GridCols;
+  colsLg?: GridCols;
+  gap?: number;
+  rowGap?: number;
+  colGap?: number;
+}
+
+const Grid = React.forwardRef<HTMLElement, GridProps>(
+  ({ as: Component = "div", cols = 1, colsSm, colsMd, colsLg, gap = 4, rowGap, colGap, className, style, ...props }, ref) => (
+    <Component
+      ref={ref}
+      className={cn(
+        "grid-layout",
+        `grid-layout--cols-${cols}`,
+        colsSm && `grid-layout--sm-cols-${colsSm}`,
+        colsMd && `grid-layout--md-cols-${colsMd}`,
+        colsLg && `grid-layout--lg-cols-${colsLg}`,
+        className,
+      )}
+      style={{
+        gap: rowGap === undefined && colGap === undefined ? spacing(gap) : undefined,
+        rowGap: rowGap !== undefined ? spacing(rowGap) : undefined,
+        columnGap: colGap !== undefined ? spacing(colGap) : undefined,
+        ...style,
+      }}
+      {...props}
+    />
+  ),
+);
+Grid.displayName = "Grid";
+
+// ---------------------------------------------------------------------------
+// Columns — asymmetric two-column layout
+// ---------------------------------------------------------------------------
+type ColumnsPreset =
+  | "sidebar"           // 280px | 1fr
+  | "sidebar-right"     // 1fr | 280px
+  | "wide-sidebar"      // 360px | 1fr
+  | "narrow-sidebar"    // 200px | 1fr
+  | "split"             // 1fr | 1fr
+  | "1-2"               // 1fr | 2fr
+  | "2-1"               // 2fr | 1fr
+  | "1-3"               // 1fr | 3fr
+  | "3-1";              // 3fr | 1fr
+
+type ColumnsCollapse = "sm" | "md" | "lg";
+
+interface ColumnsProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  preset?: ColumnsPreset;
+  template?: string;    // custom CSS grid-template-columns value
+  gap?: number;
+  colGap?: number;
+  rowGap?: number;
+  collapse?: ColumnsCollapse; // stack to single column below this breakpoint
+}
+
+const ColumnsPresetMap: Record<ColumnsPreset, string> = {
+  "sidebar":        "280px 1fr",
+  "sidebar-right":  "1fr 280px",
+  "wide-sidebar":   "360px 1fr",
+  "narrow-sidebar": "200px 1fr",
+  "split":          "1fr 1fr",
+  "1-2":            "1fr 2fr",
+  "2-1":            "2fr 1fr",
+  "1-3":            "1fr 3fr",
+  "3-1":            "3fr 1fr",
+};
+
+const Columns = React.forwardRef<HTMLElement, ColumnsProps>(
+  ({ as: Component = "div", preset = "split", template, gap = 6, colGap, rowGap, collapse, className, style, ...props }, ref) => (
+    <Component
+      ref={ref}
+      className={cn(
+        "columns-layout",
+        collapse && `columns-layout--collapse-${collapse}`,
+        className,
+      )}
+      style={{
+        gridTemplateColumns: template ?? ColumnsPresetMap[preset],
+        gap: rowGap === undefined && colGap === undefined ? spacing(gap) : undefined,
+        rowGap: rowGap !== undefined ? spacing(rowGap) : undefined,
+        columnGap: colGap !== undefined ? spacing(colGap) : undefined,
+        ...style,
+      }}
+      {...props}
+    />
+  ),
+);
+Columns.displayName = "Columns";
+
+// ---------------------------------------------------------------------------
+// Container
+// ---------------------------------------------------------------------------
+type ContainerSize = "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+
+interface ContainerProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  size?: ContainerSize;
+  center?: boolean;
+  padded?: boolean;
+}
+
+const Container = React.forwardRef<HTMLElement, ContainerProps>(
+  ({ as: Component = "div", size = "xl", center = true, padded = true, className, ...props }, ref) => (
+    <Component
+      ref={ref}
+      className={cn(
+        "container-layout",
+        `container-layout--${size}`,
+        center && "container-layout--center",
+        padded && "container-layout--padded",
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+Container.displayName = "Container";
+
+// ---------------------------------------------------------------------------
+// Section
+// ---------------------------------------------------------------------------
+type SectionPadding = "none" | "sm" | "md" | "lg" | "xl";
+
+interface SectionProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  padding?: SectionPadding;
+}
+
+const Section = React.forwardRef<HTMLElement, SectionProps>(
+  ({ as: Component = "section", padding = "lg", className, ...props }, ref) => (
+    <Component
+      ref={ref}
+      className={cn("section-layout", padding !== "none" && `section-layout--${padding}`, className)}
+      {...props}
+    />
+  ),
+);
+Section.displayName = "Section";
+
+// ---------------------------------------------------------------------------
+// AppShell — full page frame
+// ---------------------------------------------------------------------------
+interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
+  sidebarWidth?: number | string;
+  headerHeight?: number | string;
+}
+
+const AppShell = React.forwardRef<HTMLDivElement, AppShellProps>(
+  ({ sidebarWidth = "17.5rem", headerHeight = "4rem", className, style, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn("app-shell", className)}
+      style={{
+        "--app-shell-header-height": typeof headerHeight === "number" ? `${headerHeight}px` : headerHeight,
+        "--app-shell-sidebar-width": typeof sidebarWidth === "number" ? `${sidebarWidth}px` : sidebarWidth,
+        ...style,
+      } as React.CSSProperties}
+      {...props}
+    />
+  ),
+);
+AppShell.displayName = "AppShell";
+
+const AppShellHeader = React.forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(
+  ({ className, ...props }, ref) => (
+    <header ref={ref} className={cn("app-shell-header", className)} {...props} />
+  ),
+);
+AppShellHeader.displayName = "AppShellHeader";
+
+const AppShellSidebar = React.forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(
+  ({ className, ...props }, ref) => (
+    <aside ref={ref} className={cn("app-shell-sidebar", className)} {...props} />
+  ),
+);
+AppShellSidebar.displayName = "AppShellSidebar";
+
+const AppShellMain = React.forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(
+  ({ className, ...props }, ref) => (
+    <main ref={ref} className={cn("app-shell-main", className)} {...props} />
+  ),
+);
+AppShellMain.displayName = "AppShellMain";
+
+const AppShellFooter = React.forwardRef<HTMLElement, React.HTMLAttributes<HTMLElement>>(
+  ({ className, ...props }, ref) => (
+    <footer ref={ref} className={cn("app-shell-footer", className)} {...props} />
+  ),
+);
+AppShellFooter.displayName = "AppShellFooter";
+
+// ---------------------------------------------------------------------------
+// Show / Hide — responsive visibility
+// ---------------------------------------------------------------------------
+type Breakpoint = "sm" | "md" | "lg" | "xl";
+
+interface ShowProps extends React.HTMLAttributes<HTMLDivElement> {
+  above?: Breakpoint;
+  below?: Breakpoint;
+  as?: React.ElementType;
+}
+
+const Show = React.forwardRef<HTMLDivElement, ShowProps>(
+  ({ above, below, as: Component = "div", className, ...props }, ref) => (
+    <Component
+      ref={ref}
+      className={cn(
+        above && `show-above-${above}`,
+        below && `show-below-${below}`,
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+Show.displayName = "Show";
+
+interface HideProps extends React.HTMLAttributes<HTMLDivElement> {
+  above?: Breakpoint;
+  below?: Breakpoint;
+  as?: React.ElementType;
+}
+
+const Hide = React.forwardRef<HTMLDivElement, HideProps>(
+  ({ above, below, as: Component = "div", className, ...props }, ref) => (
+    <Component
+      ref={ref}
+      className={cn(
+        above && `hide-above-${above}`,
+        below && `hide-below-${below}`,
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+Hide.displayName = "Hide";
+
+// ---------------------------------------------------------------------------
+// Positioned — relative/absolute/fixed/sticky wrapper
+// ---------------------------------------------------------------------------
+type PositionType = "relative" | "absolute" | "fixed" | "sticky";
+
+interface PositionedProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  position?: PositionType;
+  top?: number | string;
+  right?: number | string;
+  bottom?: number | string;
+  left?: number | string;
+  inset?: number | string;
+  zIndex?: number;
+  fill?: boolean; // shorthand for inset: 0
+}
+
+const Positioned = React.forwardRef<HTMLElement, PositionedProps>(
+  ({ as: Component = "div", position = "relative", top, right, bottom, left, inset, zIndex, fill = false, className, style, ...props }, ref) => {
+    const resolveValue = (v: number | string | undefined) =>
+      v === undefined ? undefined : typeof v === "number" ? spacing(v) : v;
+
+    return (
+      <Component
+        ref={ref}
+        className={cn(`positioned--${position}`, className)}
+        style={{
+          top: resolveValue(top),
+          right: resolveValue(right),
+          bottom: resolveValue(bottom),
+          left: resolveValue(left),
+          inset: fill ? 0 : resolveValue(inset),
+          zIndex,
+          ...style,
+        }}
+        {...props}
+      />
+    );
+  },
+);
+Positioned.displayName = "Positioned";
+
+// ---------------------------------------------------------------------------
+// Spacer
+// ---------------------------------------------------------------------------
+interface SpacerProps {
+  size?: number;
+  axis?: "horizontal" | "vertical";
+}
+
+const Spacer = ({ size = 4, axis = "vertical" }: SpacerProps) => (
+  <div
+    aria-hidden="true"
+    style={
+      axis === "vertical"
+        ? { height: spacing(size), minHeight: spacing(size) }
+        : { width: spacing(size), minWidth: spacing(size) }
+    }
+  />
+);
+Spacer.displayName = "Spacer";
+
+export {
+  Stack,
+  Grid,
+  Columns,
+  Container,
+  Section,
+  AppShell,
+  AppShellHeader,
+  AppShellSidebar,
+  AppShellMain,
+  AppShellFooter,
+  Show,
+  Hide,
+  Positioned,
+  Spacer,
+};
+
+export type {
+  StackProps,
+  GridProps,
+  ColumnsProps,
+  ContainerProps,
+  SectionProps,
+  AppShellProps,
+  ShowProps,
+  HideProps,
+  PositionedProps,
+  SpacerProps,
+};

package/client/components/ui/sidebar.tsx

@@ -281,8 +281,12 @@ SidebarTrigger.displayName = "SidebarTrigger";
 
 const SidebarRail = React.forwardRef<
   HTMLButtonElement,
-  React.ComponentProps<"button">
->(({ className, ...props }, ref) => {
+  React.ComponentProps<"button"> & {
+    side?: "left" | "right";
+    state?: "expanded" | "collapsed";
+    collapsible?: "offcanvas" | "icon" | "none";
+  }
+>(({ className, side, state, collapsible, ...props }, ref) => {
   const { toggleSidebar } = useSidebar();
 
   return (
@@ -308,8 +312,11 @@ SidebarRail.displayName = "SidebarRail";
 
 const SidebarInset = React.forwardRef<
   HTMLDivElement,
-  React.ComponentProps<"main">
->(({ className, ...props }, ref) => {
+  React.ComponentProps<"main"> & {
+    state?: "expanded" | "collapsed";
+    variant?: "sidebar" | "floating" | "inset";
+  }
+>(({ className, state, variant, ...props }, ref) => {
   return (
     <main
       ref={ref}
@@ -707,7 +714,6 @@ const SidebarMenuSubButton = React.forwardRef<
         size === "md" && "sidebar-menu-sub-button--size-md",
         className,
       )}
-      data-size={size}
       {...props}
     />
   );

package/client/components/ui/stepper.tsx

@@ -0,0 +1,148 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+export interface StepItem {
+  title: string;
+  description?: string;
+}
+
+type StepStatus = "complete" | "current" | "upcoming";
+type StepperOrientation = "horizontal" | "vertical";
+type StepperVariant = "default" | "outlined";
+type StepperSize = "sm" | "md" | "lg";
+
+export interface StepperProps {
+  steps: StepItem[];
+  currentStep: number; // 0-indexed
+  orientation?: StepperOrientation;
+  variant?: StepperVariant;
+  size?: StepperSize;
+  onStepClick?: (index: number) => void;
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function getStatus(index: number, currentStep: number): StepStatus {
+  if (index < currentStep) return "complete";
+  if (index === currentStep) return "current";
+  return "upcoming";
+}
+
+const CheckIcon = () => (
+  <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+    <path
+      d="M2.5 7L5.5 10L11.5 4"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+// ---------------------------------------------------------------------------
+// Stepper
+// ---------------------------------------------------------------------------
+const Stepper = React.forwardRef<HTMLDivElement, StepperProps>(
+  (
+    {
+      steps,
+      currentStep,
+      orientation = "horizontal",
+      variant = "default",
+      size = "md",
+      onStepClick,
+      className,
+    },
+    ref,
+  ) => {
+    return (
+      <div
+        ref={ref}
+        role="list"
+        aria-label="Progress steps"
+        className={cn(
+          "stepper",
+          `stepper--${orientation}`,
+          `stepper--${size}`,
+          className,
+        )}
+      >
+        {steps.map((step, index) => {
+          const status = getStatus(index, currentStep);
+          const isClickable = !!onStepClick && status === "complete";
+          const isLast = index === steps.length - 1;
+
+          return (
+            <div
+              key={index}
+              role="listitem"
+              aria-current={status === "current" ? "step" : undefined}
+              className={cn(
+                "stepper-item",
+                `stepper-item--${status}`,
+                orientation === "horizontal" && !isLast && "stepper-item--with-connector",
+              )}
+            >
+              {/* Indicator + connector row */}
+              <div className="stepper-indicator-row">
+                {/* Circle */}
+                <button
+                  type="button"
+                  disabled={!isClickable}
+                  onClick={() => isClickable && onStepClick(index)}
+                  className={cn(
+                    "stepper-indicator",
+                    `stepper-indicator--${status}`,
+                    `stepper-indicator--${variant}`,
+                    isClickable && "stepper-indicator--clickable",
+                  )}
+                  aria-label={`Step ${index + 1}: ${step.title} (${status})`}
+                >
+                  {status === "complete" ? (
+                    <CheckIcon />
+                  ) : (
+                    <span className="stepper-indicator-number">{index + 1}</span>
+                  )}
+                </button>
+
+                {/* Connector line — horizontal: after indicator, vertical: below */}
+                {!isLast && (
+                  <div
+                    className={cn(
+                      "stepper-connector",
+                      `stepper-connector--${orientation}`,
+                      index < currentStep && "stepper-connector--complete",
+                    )}
+                    aria-hidden="true"
+                  />
+                )}
+              </div>
+
+              {/* Label */}
+              <div className="stepper-label">
+                <span className={cn("stepper-title", `stepper-title--${status}`)}>
+                  {step.title}
+                </span>
+                {step.description && (
+                  <span className={cn("stepper-description", `stepper-description--${status}`)}>
+                    {step.description}
+                  </span>
+                )}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    );
+  },
+);
+
+Stepper.displayName = "Stepper";
+
+export { Stepper };

package/client/components/ui/system-bar.tsx

@@ -0,0 +1,119 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+// ─── SystemBar Root ───────────────────────────────────────────────────────────
+
+export interface SystemBarProps extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * Background color — any CSS color or var() token.
+   * When set, text and icons automatically switch to white for contrast.
+   */
+  color?: string;
+  /**
+   * Window mode: renders a desktop-style title bar with
+   * message indicator on the left and window controls on the right.
+   */
+  window?: boolean;
+  /** Height of the bar in px (default 24 for status bar, 32 for window) */
+  height?: number;
+}
+
+const SystemBar = React.forwardRef<HTMLElement, SystemBarProps>(
+  (
+    {
+      className,
+      children,
+      color,
+      window: isWindow = false,
+      height,
+      style,
+      ...props
+    },
+    ref
+  ) => {
+    const barHeight = height ?? (isWindow ? 32 : 24);
+
+    return (
+      <header
+        ref={ref}
+        role="banner"
+        style={{
+          height: barHeight,
+          backgroundColor: color,
+          ...style,
+        }}
+        className={cn(
+          "system-bar",
+          isWindow && "system-bar--window",
+          color && "system-bar--colored",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </header>
+    );
+  }
+);
+SystemBar.displayName = "SystemBar";
+
+// ─── SystemBarSpacer ──────────────────────────────────────────────────────────
+// Pushes content to the right (flex: 1).
+
+export interface SystemBarSpacerProps
+  extends React.HTMLAttributes<HTMLSpanElement> {}
+
+const SystemBarSpacer = React.forwardRef<HTMLSpanElement, SystemBarSpacerProps>(
+  ({ className, ...props }, ref) => (
+    <span
+      ref={ref}
+      className={cn("system-bar-spacer", className)}
+      {...props}
+    />
+  )
+);
+SystemBarSpacer.displayName = "SystemBarSpacer";
+
+// ─── SystemBarIcon ────────────────────────────────────────────────────────────
+// Thin wrapper so icon children pick up the right size + color.
+
+export interface SystemBarIconProps
+  extends React.HTMLAttributes<HTMLSpanElement> {}
+
+const SystemBarIcon = React.forwardRef<HTMLSpanElement, SystemBarIconProps>(
+  ({ className, ...props }, ref) => (
+    <span
+      ref={ref}
+      className={cn("system-bar-icon", className)}
+      {...props}
+    />
+  )
+);
+SystemBarIcon.displayName = "SystemBarIcon";
+
+// ─── SystemBarAction ──────────────────────────────────────────────────────────
+// Icon button used in window mode (minimise / maximise / close).
+
+export interface SystemBarActionProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  "aria-label": string;
+}
+
+const SystemBarAction = React.forwardRef<
+  HTMLButtonElement,
+  SystemBarActionProps
+>(({ className, children, ...props }, ref) => (
+  <button
+    ref={ref}
+    type="button"
+    className={cn("system-bar-action", className)}
+    {...props}
+  >
+    {children}
+  </button>
+));
+SystemBarAction.displayName = "SystemBarAction";
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+export { SystemBar, SystemBarSpacer, SystemBarIcon, SystemBarAction };