@sixthshift/design-system 0.1.0

package/src/lib/contexts/OverlayContext/hooks/useToast.ts

@@ -0,0 +1,80 @@
+import type { StackItem } from "@sixthshift/design-system/hooks";
+import { Toast, type ToastProps } from "@sixthshift/design-system/toast";
+import { type FunctionComponent, useCallback, useEffect, useId, useRef } from "react";
+import { useOverlayContext } from "../OverlayContext";
+
+// Default auto-dismiss duration in milliseconds
+const DEFAULT_DURATION = 5000;
+
+// Native replacements for lodash functions
+const isFunction = (value: unknown): value is FunctionComponent<ToastProps> => typeof value === "function";
+
+const isPlainObject = (value: unknown): value is ToastPropsWithDuration => typeof value === "object" && value !== null && !Array.isArray(value);
+
+type ToastPropsWithDuration = Omit<ToastProps, "onClose"> & {
+  /** Auto-dismiss duration in ms. Set to 0 to disable. Default: 5000 */
+  duration?: number;
+};
+
+/**
+ * Toast stack item - extends base StackItem with component and additional props
+ * that are passed through to the Toast component in OverlayContext
+ */
+type ToastStackItem = StackItem & {
+  component: FunctionComponent<ToastProps>;
+  onClose?: () => void;
+} & Partial<Omit<ToastProps, "onClose">>;
+
+export const useToast = (args: ToastPropsWithDuration | FunctionComponent<ToastProps>) => {
+  const {
+    toastStack: [, dispatch],
+  } = useOverlayContext();
+
+  const id = useId();
+
+  const customComponent = isFunction(args) ? args : null;
+  const props = isPlainObject(args) ? args : ({} as ToastPropsWithDuration);
+  const { duration = DEFAULT_DURATION, ...toastPropsRaw } = props;
+
+  const closeToast = useCallback(() => {
+    dispatch({ type: "remove", id, transition: { duration: 300 } });
+  }, [dispatch, id]);
+
+  // `openToast` has to be both referentially stable — callers put it in effect
+  // dependency arrays — and able to see the current props. A ref refreshed after
+  // every render gives both.
+  //
+  // It previously memoised the props object against JSON.stringify(props) as a
+  // cache key. JSON.stringify silently drops function-valued properties, so a
+  // changed `onAction` whose serialisable fields were identical did not
+  // invalidate the key, and `openToast` kept firing the stale closure.
+  const latest = useRef({ customComponent, toastProps: toastPropsRaw, duration });
+  useEffect(() => {
+    latest.current = { customComponent, toastProps: toastPropsRaw, duration };
+  });
+
+  const openToast = useCallback(() => {
+    const { customComponent: component, toastProps, duration: autoDismiss } = latest.current;
+
+    dispatch({
+      type: "push",
+      item: {
+        id,
+        component: component ?? Toast,
+        onClose: closeToast,
+        standalone: false, // OverlayContext handles positioning
+        ...toastProps,
+      } as ToastStackItem,
+    });
+
+    // Auto-dismiss if duration is set
+    if (autoDismiss > 0) {
+      setTimeout(closeToast, autoDismiss);
+    }
+  }, [dispatch, id, closeToast]);
+
+  return {
+    openToast,
+    closeToast,
+  };
+};

package/src/lib/contexts/OverlayContext/index.ts

@@ -0,0 +1,6 @@
+export type { ModalProps } from "@sixthshift/design-system/modal";
+// Re-export Modal from primitives for convenience
+export { Modal } from "@sixthshift/design-system/modal";
+export * from "./hooks/useModal";
+export * from "./hooks/useToast";
+export * from "./OverlayContext";

package/src/lib/format.ts

@@ -0,0 +1,51 @@
+/**
+ * Formatting utilities for common display patterns
+ */
+
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB", "PB"] as const;
+
+/**
+ * Format a byte count for display, e.g. `formatBytes(1536)` -> `"1.50 KB"`.
+ *
+ * Total over every finite input:
+ * - negative values format their magnitude with a leading sign, so the function
+ *   is usable for deltas
+ * - values above the largest unit stay in PB rather than running off the end of
+ *   the unit list (PB already exceeds Number.MAX_SAFE_INTEGER bytes)
+ * - values below 1 byte stay in B
+ *
+ * Non-finite input (NaN, +/-Infinity) has no representation, so it returns an
+ * em dash rather than a number that would be wrong.
+ */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes)) return "—";
+  if (bytes === 0) return "0 B";
+
+  // Repeated division rather than Math.log(bytes) / Math.log(1024): it is exact
+  // at the unit boundaries, needs no clamping of a computed index, and cannot
+  // produce a negative or out-of-range index for very small or very large input.
+  let value = Math.abs(bytes);
+  let unit = 0;
+  while (value >= 1024 && unit < BYTE_UNITS.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+
+  return `${bytes < 0 ? "-" : ""}${value.toFixed(2)} ${BYTE_UNITS[unit]}`;
+}
+
+/**
+ * Format seconds to human-readable uptime (e.g., "2d 5h 30m")
+ */
+export function formatUptime(seconds: number): string {
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+
+  const parts: string[] = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+
+  return parts.length > 0 ? parts.join(" ") : "< 1m";
+}

package/src/lib/utils.ts

@@ -0,0 +1,10 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Merge Tailwind classes with clsx
+ * Handles conditional classes and resolves conflicts
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/lib/withEmpty.tsx

@@ -0,0 +1,14 @@
+import type { ComponentType, ReactNode } from "react";
+
+export function withEmpty<P extends object>(Component: ComponentType<P>, isEmpty: (props: P) => boolean, fallback: ReactNode) {
+  function WithEmpty(props: P) {
+    if (isEmpty(props)) {
+      return <>{fallback}</>;
+    }
+    return <Component {...props} />;
+  }
+
+  WithEmpty.displayName = `withEmpty(${Component.displayName || Component.name || "Component"})`;
+
+  return WithEmpty;
+}

package/src/lib/withErrorBoundary.tsx

@@ -0,0 +1,16 @@
+import type { ComponentType, ReactNode } from "react";
+import { ErrorBoundary, type ErrorFallbackProps } from "./ErrorBoundary";
+
+export function withErrorBoundary<P extends object>(Component: ComponentType<P>, fallback: ReactNode | ((props: ErrorFallbackProps) => ReactNode)) {
+  function WithErrorBoundary(props: P) {
+    return (
+      <ErrorBoundary fallback={fallback}>
+        <Component {...props} />
+      </ErrorBoundary>
+    );
+  }
+
+  WithErrorBoundary.displayName = `withErrorBoundary(${Component.displayName || Component.name || "Component"})`;
+
+  return WithErrorBoundary;
+}

package/src/lib/withSuspense.tsx

@@ -0,0 +1,16 @@
+import type { ComponentType, ReactNode } from "react";
+import { Suspense } from "react";
+
+export function withSuspense<P extends object>(Component: ComponentType<P>, fallback: ReactNode) {
+  function WithSuspense(props: P) {
+    return (
+      <Suspense fallback={fallback}>
+        <Component {...props} />
+      </Suspense>
+    );
+  }
+
+  WithSuspense.displayName = `withSuspense(${Component.displayName || Component.name || "Component"})`;
+
+  return WithSuspense;
+}

package/src/lib/withSuspenseAndErrorBoundary.tsx

@@ -0,0 +1,26 @@
+import type { ComponentType, ReactNode } from "react";
+import { Suspense } from "react";
+import { ErrorBoundary, type ErrorFallbackProps } from "./ErrorBoundary";
+
+type Options = {
+  fallback: ReactNode;
+  errorFallback: ReactNode | ((props: ErrorFallbackProps) => ReactNode);
+};
+
+export function withSuspenseAndErrorBoundary<P extends object>(Component: ComponentType<P>, options: Options) {
+  const { fallback, errorFallback } = options;
+
+  function WithSuspenseAndErrorBoundary(props: P) {
+    return (
+      <ErrorBoundary fallback={errorFallback}>
+        <Suspense fallback={fallback}>
+          <Component {...props} />
+        </Suspense>
+      </ErrorBoundary>
+    );
+  }
+
+  WithSuspenseAndErrorBoundary.displayName = `withSuspenseAndErrorBoundary(${Component.displayName || Component.name || "Component"})`;
+
+  return WithSuspenseAndErrorBoundary;
+}

package/src/styles/base.css

@@ -0,0 +1,41 @@
+/**
+ * PA Design System - Global Styles
+ *
+ * Theme tokens (CSS variables) are provided by @sixthshift/design-system/theme.css
+ * which is generated from src/theme/theme.json and src/theme/palette.json
+ *
+ * Import order in consumers:
+ *   import '@sixthshift/design-system/theme.css';   // CSS variables
+ *   import '@sixthshift/design-system/styles.css';  // Tailwind + base styles
+ */
+
+@import "tailwindcss";
+@config "../../tailwind.config.ts";
+
+/* =============================================================================
+   BASE STYLES
+   ============================================================================= */
+
+@layer base {
+  * {
+    @apply border-border-normal;
+  }
+
+  body {
+    @apply bg-bg-normal text-fg-normal;
+    font-family: var(--font-sans);
+    font-feature-settings:
+      'rlig' 1,
+      'calt' 1;
+  }
+
+  /* Smooth scrolling */
+  html {
+    scroll-behavior: smooth;
+  }
+
+  /* Focus visible for keyboard navigation */
+  :focus-visible {
+    @apply outline-hidden ring-2 ring-focus-ring ring-offset-2 ring-offset-bg-normal;
+  }
+}

package/src/theme/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Theme Exports
+ *
+ * Re-exports schema types and utilities for use in other packages.
+ */
+
+export type {
+  BgKey,
+  BgToken,
+  BorderKey,
+  BorderToken,
+  ColorMode,
+  ColorModeSchema,
+  ColorToken,
+  Context,
+  CSSVarName,
+  Feedback,
+  FgKey,
+  FgToken,
+  HexValue,
+  Hierarchy,
+  HSLValue,
+  Semantic,
+  ThemeSchema,
+  TokenKey,
+} from "./schema";
+
+export {
+  contexts,
+  cssVar,
+  feedback,
+  getAllTokenNames,
+  getTokenNames,
+  hierarchy,
+  hsl,
+  semantics,
+} from "./schema";

package/src/theme/palette.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "./palette.schema.json",
+  "emerald": {
+    "50": "#f2fafb",
+    "100": "#d6eef0",
+    "200": "#addde0",
+    "300": "#7cc4c8",
+    "400": "#4ba5a9",
+    "500": "#368086",
+    "600": "#2c666c",
+    "700": "#234e53",
+    "800": "#19393d",
+    "900": "#11292c",
+    "950": "#0a1a1d"
+  },
+
+  "topaz": {
+    "50": "#fff7f0",
+    "100": "#ffe5d1",
+    "200": "#fbc89f",
+    "300": "#f0a066",
+    "400": "#d9722e",
+    "500": "#c4530a",
+    "600": "#9f4007",
+    "700": "#7b2e06",
+    "800": "#5a2105",
+    "900": "#3d1503",
+    "950": "#230c02"
+  },
+
+  "ruby": {
+    "50": "#fff5f6",
+    "100": "#fde1e4",
+    "200": "#f8bac3",
+    "300": "#ec8796",
+    "400": "#d55368",
+    "500": "#c33341",
+    "600": "#9e2533",
+    "700": "#7a1b27",
+    "800": "#57131c",
+    "900": "#3a0c13",
+    "950": "#21070b"
+  },
+
+  "ocean": {
+    "50": "#f0f4fa",
+    "100": "#dce6f4",
+    "200": "#b9cde9",
+    "300": "#8fafd9",
+    "400": "#6691c7",
+    "500": "#4573ae",
+    "600": "#355a8c",
+    "700": "#034078",
+    "800": "#022f5a",
+    "900": "#001f54",
+    "950": "#0a1128"
+  },
+
+  "sky": {
+    "50": "#effcff",
+    "100": "#d6f5fb",
+    "200": "#b3ecf7",
+    "300": "#7fdff0",
+    "400": "#44c9e2",
+    "500": "#1282a2",
+    "600": "#0f6b86",
+    "700": "#10576d",
+    "800": "#12475a",
+    "900": "#133c4c",
+    "950": "#062733"
+  },
+
+  "earth": {
+    "50": "#fefcfb",
+    "100": "#faf6f4",
+    "200": "#f2ebe7",
+    "300": "#e8ddd6",
+    "400": "#d4c4b9",
+    "500": "#b8a192",
+    "600": "#9a816f",
+    "700": "#7d6555",
+    "800": "#5e4b40",
+    "900": "#3d302a",
+    "950": "#211916"
+  },
+
+  "slate": {
+    "50": "#f8fafc",
+    "100": "#f1f5f9",
+    "200": "#e2e8f0",
+    "300": "#cbd5e1",
+    "400": "#94a3b8",
+    "500": "#64748b",
+    "600": "#475569",
+    "700": "#334155",
+    "800": "#1e293b",
+    "900": "#0f172a",
+    "950": "#020617"
+  }
+}

package/src/theme/palette.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PA Palette",
+  "description": "Color palette definition for Personal Assistant",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/colorScale"
+  },
+  "$defs": {
+    "hexColor": {
+      "type": "string",
+      "pattern": "^#[0-9a-fA-F]{6}$",
+      "description": "Hex color value (e.g., #818cf8)"
+    },
+    "colorScale": {
+      "type": "object",
+      "description": "A color scale with steps from 50 to 950",
+      "properties": {
+        "50": { "$ref": "#/$defs/hexColor", "description": "Lightest shade" },
+        "100": { "$ref": "#/$defs/hexColor" },
+        "200": { "$ref": "#/$defs/hexColor" },
+        "300": { "$ref": "#/$defs/hexColor" },
+        "400": { "$ref": "#/$defs/hexColor" },
+        "500": { "$ref": "#/$defs/hexColor", "description": "Base shade" },
+        "600": { "$ref": "#/$defs/hexColor" },
+        "700": { "$ref": "#/$defs/hexColor" },
+        "800": { "$ref": "#/$defs/hexColor" },
+        "900": { "$ref": "#/$defs/hexColor" },
+        "950": { "$ref": "#/$defs/hexColor", "description": "Darkest shade" }
+      },
+      "required": ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950"],
+      "additionalProperties": false
+    }
+  }
+}

package/src/theme/schema.ts

@@ -0,0 +1,122 @@
+/**
+ * Theme Schema
+ *
+ * Type definitions for the PA design system token structure.
+ * These types enforce the naming convention: {context}-{semantic}
+ */
+
+// =============================================================================
+// PRIMITIVES
+// =============================================================================
+
+/** HSL color value without wrapper, e.g., "239 84% 67%" */
+export type HSLValue = string;
+
+/** Hex color value, e.g., "#6366f1" */
+export type HexValue = string;
+
+/** Color mode */
+export type ColorMode = "light" | "dark";
+
+// =============================================================================
+// TOKEN STRUCTURE
+// =============================================================================
+
+/** Contexts - what CSS property this affects */
+export const contexts = ["bg", "fg", "border"] as const;
+export type Context = (typeof contexts)[number];
+
+/** Hierarchy semantics - visual weight */
+export const hierarchy = ["strong", "normal", "subtle"] as const;
+export type Hierarchy = (typeof hierarchy)[number];
+
+/** Feedback semantics - meaning */
+export const feedback = ["success", "warning", "danger"] as const;
+export type Feedback = (typeof feedback)[number];
+
+/** All semantics */
+export const semantics = [...hierarchy, ...feedback] as const;
+export type Semantic = (typeof semantics)[number];
+
+// =============================================================================
+// TOKEN NAMES (derived types)
+// =============================================================================
+
+/** Background tokens: bg-{semantic} */
+export type BgToken = `bg-${Semantic}`;
+
+/** Foreground tokens: fg-{semantic} | fg-on-{semantic} */
+export type FgToken = `fg-${Semantic}` | `fg-on-${Semantic}`;
+
+/** Border tokens: border-{semantic} */
+export type BorderToken = `border-${Semantic}`;
+
+/** All color tokens */
+export type ColorToken = BgToken | FgToken | BorderToken;
+
+/** CSS variable name format */
+export type CSSVarName = `--${ColorToken}`;
+
+// =============================================================================
+// THEME SCHEMA
+// =============================================================================
+
+/** Background token keys */
+export type BgKey = `bg-${Semantic}`;
+
+/** Foreground token keys */
+export type FgKey = `fg-${Semantic}` | `fg-on-${Semantic}`;
+
+/** Border token keys */
+export type BorderKey = `border-${Semantic}`;
+
+/** All token keys */
+export type TokenKey = BgKey | FgKey | BorderKey;
+
+/** Color mode schema (light or dark) - flat structure */
+export type ColorModeSchema = {
+  [K in TokenKey]: HexValue;
+};
+
+/** Complete theme schema */
+export type ThemeSchema = {
+  $schema?: string;
+  name: string;
+  version: string;
+  light: ColorModeSchema;
+  dark: ColorModeSchema;
+};
+
+// =============================================================================
+// UTILITIES
+// =============================================================================
+
+/** Get all token names for a context */
+export function getTokenNames(context: "bg"): BgToken[];
+export function getTokenNames(context: "fg"): FgToken[];
+export function getTokenNames(context: "border"): BorderToken[];
+export function getTokenNames(context: Context): ColorToken[] {
+  switch (context) {
+    case "bg":
+      return semantics.map((s) => `bg-${s}` as BgToken);
+    case "fg":
+      return [...semantics.map((s) => `fg-${s}` as FgToken), ...semantics.map((s) => `fg-on-${s}` as FgToken)];
+    case "border":
+      return semantics.map((s) => `border-${s}` as BorderToken);
+  }
+}
+
+/** Get all token names */
+export function getAllTokenNames(): ColorToken[] {
+  return [...getTokenNames("bg"), ...getTokenNames("fg"), ...getTokenNames("border")];
+}
+
+/** Type-safe CSS var reference */
+export function cssVar(token: ColorToken): string {
+  return `var(--${token})`;
+}
+
+/** Type-safe HSL wrapper for Tailwind */
+export function hsl(token: ColorToken): string {
+  return `hsl(var(--${token}))`;
+}