argent-grid 0.1.0 → 0.2.0

package/src/lib/themes/theme-builder.ts

@@ -0,0 +1,347 @@
+/**
+ * Theme Builder - Create and customize themes programmatically
+ *
+ * Inspired by AG Grid's new Theming API (v32.2+)
+ */
+
+import type {
+  PartialThemeParameters,
+  GridThemeObject as Theme,
+  ThemeBuilder,
+  ThemeParameters,
+  ThemePart,
+} from './types';
+
+// ============================================================================
+// THEME BUILDER CLASS
+// ============================================================================
+
+/**
+ * Theme builder class for creating and customizing themes
+ */
+class ThemeBuilderImpl implements ThemeBuilder {
+  public readonly name: string;
+  public readonly description?: string;
+  public readonly parameters: ThemeParameters;
+  public readonly parts: ThemePart[];
+
+  constructor(config: {
+    name: string;
+    description?: string;
+    parameters: ThemeParameters;
+    parts?: ThemePart[];
+  }) {
+    this.name = config.name;
+    this.description = config.description;
+    this.parameters = config.parameters;
+    this.parts = config.parts || [];
+  }
+
+  /**
+   * Create a new theme with overridden parameters
+   *
+   * @example
+   * ```typescript
+   * const myTheme = themeQuartz.withParams({
+   *   spacing: 12,
+   *   accentColor: 'red',
+   *   fontSize: 14,
+   * });
+   * ```
+   */
+  withParams(params: PartialThemeParameters): ThemeBuilder {
+    const mergedParams = {
+      ...this.parameters,
+      ...params,
+    };
+
+    return new ThemeBuilderImpl({
+      name: this.name,
+      description: this.description,
+      parameters: mergedParams,
+      parts: this.parts,
+    });
+  }
+
+  /**
+   * Add a theme part to the theme
+   *
+   * @example
+   * ```typescript
+   * const myTheme = themeQuartz
+   *   .withPart(colorSchemeDark)
+   *   .withPart(iconSetMaterial);
+   * ```
+   */
+  withPart(part: ThemePart): ThemeBuilder {
+    return new ThemeBuilderImpl({
+      name: this.name,
+      description: this.description,
+      parameters: this.parameters,
+      parts: [...this.parts, part],
+    });
+  }
+
+  /**
+   * Get the final theme object with all parts applied
+   */
+  build(): Theme {
+    return {
+      name: this.name,
+      description: this.description,
+      parameters: this.parameters,
+      parts: this.parts,
+    };
+  }
+
+  /**
+   * Convert theme to CSS custom properties
+   */
+  toCSS(): string {
+    const cssVars: string[] = [];
+
+    // Convert parameters to CSS custom properties
+    Object.entries(this.parameters).forEach(([key, value]) => {
+      const cssVarName = camelToKebab(key);
+      cssVars.push(`  --ag-${cssVarName}: ${value};`);
+    });
+
+    // Add parts CSS
+    this.parts.forEach((part) => {
+      if (part.css) {
+        cssVars.push(part.css);
+      }
+    });
+
+    return `:root {\n${cssVars.join('\n')}\n}`;
+  }
+}
+
+// ============================================================================
+// THEME CREATION FUNCTIONS
+// ============================================================================
+
+/**
+ * Create a new theme
+ *
+ * @example
+ * ```typescript
+ * const myTheme = createTheme({
+ *   name: 'my-theme',
+ *   description: 'My custom theme',
+ *   parameters: {
+ *     accentColor: 'blue',
+ *     spacing: 12,
+ *   },
+ * });
+ * ```
+ */
+export function createTheme(config: {
+  name: string;
+  description?: string;
+  parameters: ThemeParameters;
+  parts?: ThemePart[];
+}): ThemeBuilder {
+  return new ThemeBuilderImpl(config);
+}
+
+/**
+ * Create a theme by extending an existing theme
+ *
+ * @example
+ * ```typescript
+ * const myTheme = extendTheme(themeQuartz, {
+ *   accentColor: 'red',
+ *   spacing: 12,
+ * });
+ * ```
+ */
+export function extendTheme(baseTheme: ThemeBuilder, params: PartialThemeParameters): ThemeBuilder {
+  return baseTheme.withParams(params);
+}
+
+/**
+ * Merge multiple themes together
+ * Later themes override earlier ones
+ */
+export function mergeThemes(...themes: ThemeBuilder[]): ThemeBuilder {
+  if (themes.length === 0) {
+    throw new Error('At least one theme is required');
+  }
+
+  const baseTheme = themes[0];
+  const mergedParams = { ...baseTheme.parameters };
+  const mergedParts = [...baseTheme.parts];
+
+  for (let i = 1; i < themes.length; i++) {
+    const theme = themes[i];
+    Object.assign(mergedParams, theme.parameters);
+    mergedParts.push(...theme.parts);
+  }
+
+  return new ThemeBuilderImpl({
+    name: 'merged',
+    parameters: mergedParams,
+    parts: mergedParts,
+  });
+}
+
+// ============================================================================
+// UTILITIES
+// ============================================================================
+
+/**
+ * Convert camelCase to kebab-case
+ */
+function camelToKebab(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+/**
+ * Get CSS variables from theme as a map
+ * Returns CSS custom properties that can be applied to an element's style
+ */
+export function getThemeCSSVariables(theme: ThemeBuilder): Record<string, string> {
+  const params = theme.parameters;
+  const parts = theme.parts;
+
+  // Collect all parameters from theme and parts
+  let allParams = { ...params };
+
+  // Merge parameters from all parts (later parts override earlier ones)
+  for (const part of parts) {
+    if (part.params) {
+      allParams = { ...allParams, ...part.params };
+    }
+  }
+
+  // Map to CSS variables
+  return {
+    '--ag-background-color': allParams.backgroundColor || allParams.rowBackgroundColor || '#ffffff',
+    '--ag-foreground-color': allParams.foregroundColor || '#181d1f',
+    '--ag-secondary-foreground-color': allParams.secondaryForegroundColor || '#666666',
+    '--ag-header-background-color': allParams.headerBackgroundColor || '#f8f9fa',
+    '--ag-header-foreground-color': allParams.foregroundColor || '#181d1f',
+    '--ag-odd-row-background-color': allParams.rowEvenBackgroundColor || '#f8f9fa',
+    '--ag-row-hover-color':
+      allParams.rowHoverBackgroundColor || allParams.cellHoverBackgroundColor || '#f0f2f5',
+    '--ag-selected-row-background-color': allParams.rowSelectedBackgroundColor || '#e3f2fd',
+    '--ag-border-color': allParams.borderColor || '#babed1',
+    '--ag-cell-horizontal-padding': `${String(allParams.cellPadding || allParams.spacing || 8)}px`,
+    '--ag-header-height': `${String(allParams.headerHeight || 48)}px`,
+    '--ag-row-height': `${String(allParams.rowHeight || 32)}px`,
+    '--ag-font-size': `${String(allParams.fontSize || 14)}px`,
+    '--ag-font-family':
+      allParams.fontFamily || '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+  };
+}
+
+/**
+ * Apply theme CSS variables to a specific element
+ * This updates both the element's inline styles and any CSS that uses these variables
+ */
+export function applyThemeCSSVariables(theme: ThemeBuilder, element: HTMLElement): void {
+  const cssVars = getThemeCSSVariables(theme);
+
+  Object.entries(cssVars).forEach(([key, value]) => {
+    element.style.setProperty(key, value);
+  });
+}
+
+/**
+ * Apply theme to a container element
+ * Injects CSS custom properties
+ */
+export function applyTheme(
+  theme: ThemeBuilder,
+  container: HTMLElement | ShadowRoot = document.documentElement
+): void {
+  const css = theme.toCSS();
+
+  // Remove existing theme styles
+  const existingStyle = container.querySelector('style[data-ag-theme]');
+  if (existingStyle) {
+    existingStyle.remove();
+  }
+
+  // Create new style element
+  const style = document.createElement('style');
+  style.setAttribute('data-ag-theme', theme.name);
+  style.textContent = css;
+
+  // Append to container
+  container.appendChild(style);
+}
+
+/**
+ * Remove theme from a container element
+ */
+export function removeTheme(
+  theme: ThemeBuilder,
+  container: HTMLElement | ShadowRoot = document.documentElement
+): void {
+  const existingStyle = container.querySelector(`style[data-ag-theme="${theme.name}"]`);
+  if (existingStyle) {
+    existingStyle.remove();
+  }
+}
+
+// ============================================================================
+// THEME CONVERTER - Convert ThemeBuilder to Canvas Renderer format
+// ============================================================================
+
+/**
+ * Convert ThemeBuilder parameters to internal GridTheme format
+ * This allows the new Theming API to work with the canvas renderer
+ */
+export function convertThemeToGridTheme(theme: ThemeBuilder): Record<string, any> {
+  const params = theme.parameters;
+  const parts = theme.parts;
+
+  // Collect all parameters from theme and parts
+  let allParams = { ...params };
+
+  // Merge parameters from all parts (later parts override earlier ones)
+  for (const part of parts) {
+    if (part.params) {
+      allParams = { ...allParams, ...part.params };
+    }
+  }
+
+  // Map ThemeParameters to internal GridTheme format
+  const gridTheme: Record<string, any> = {
+    // Background colors
+    bgCell: allParams.backgroundColor || allParams.rowBackgroundColor || '#ffffff',
+    bgCellEven: allParams.rowEvenBackgroundColor || '#f8f9fa',
+    bgHeader: allParams.headerBackgroundColor || '#f8f9fa',
+    bgSelection: allParams.rowSelectedBackgroundColor || '#e3f2fd',
+    bgHover: allParams.rowHoverBackgroundColor || allParams.cellHoverBackgroundColor || '#f0f2f5',
+    bgGroupRow: allParams.groupRowBackgroundColor || '#f5f5f5',
+
+    // Text colors
+    textCell: allParams.foregroundColor || '#181d1f',
+    textHeader: allParams.foregroundColor || '#181d1f',
+
+    // Typography
+    fontFamily:
+      allParams.fontFamily || '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    fontSize: allParams.fontSize || 14,
+    fontWeight: allParams.fontWeight || 'normal',
+
+    // Borders
+    borderColor: allParams.borderColor || '#babed1',
+    headerBorderColor: allParams.borderColor || '#babed1',
+    gridLineColor: allParams.borderColor || '#babed1',
+
+    // Spacing
+    cellPadding: allParams.cellPadding || allParams.spacing || 8,
+    headerHeight: allParams.headerHeight || 48,
+    rowHeight: allParams.rowHeight || 32,
+
+    // Group/Tree
+    groupIndentWidth: allParams.groupRowIndentWidth || 24,
+    groupIndicatorSize: allParams.iconSize || 12,
+  };
+
+  return gridTheme;
+}

package/src/lib/themes/theme-quartz.ts

@@ -0,0 +1,72 @@
+/**
+ * Quartz Theme - Modern, high-contrast theme
+ * Recommended for most applications
+ */
+
+import { createTheme } from './theme-builder';
+import type { ThemeParameters } from './types';
+
+// Default Quartz theme parameters
+const QUARTZ_DEFAULTS: ThemeParameters = {
+  // Colors
+  accentColor: '#1976d2',
+  backgroundColor: '#ffffff',
+  foregroundColor: '#181d1f',
+  secondaryForegroundColor: '#666666',
+
+  // Typography
+  fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+  fontSize: 14,
+  fontWeight: 400,
+  headerFontWeight: 600,
+
+  // Spacing
+  spacing: 8,
+  rowHeight: 48,
+  headerHeight: 48,
+  cellPadding: 12,
+
+  // Borders
+  borderColor: '#dcdcdc',
+  borderWidth: 1,
+  borderRadius: 0,
+
+  // Specific colors
+  headerBackgroundColor: '#f5f5f5',
+  rowBackgroundColor: '#ffffff',
+  rowEvenBackgroundColor: '#fafafa',
+  rowHoverBackgroundColor: '#f0f0f0',
+  rowSelectedBackgroundColor: '#e3f2fd',
+  cellHoverBackgroundColor: '#f5f5f5',
+
+  // Group row
+  groupRowBackgroundColor: '#fafafa',
+  groupRowIndentWidth: 24,
+};
+
+/**
+ * Quartz theme object
+ *
+ * @example
+ * ```typescript
+ * import { themeQuartz } from 'argent-grid';
+ *
+ * // Basic usage
+ * gridOptions.theme = themeQuartz;
+ *
+ * // Customization
+ * const myTheme = themeQuartz.withParams({
+ *   spacing: 12,
+ *   accentColor: 'red',
+ * });
+ *
+ * // Mix with parts
+ * import { colorSchemeDark } from 'argent-grid';
+ * const myTheme = themeQuartz.withPart(colorSchemeDark);
+ * ```
+ */
+export const themeQuartz = createTheme({
+  name: 'quartz',
+  description: 'Modern, high-contrast theme recommended for most applications',
+  parameters: QUARTZ_DEFAULTS,
+});

package/src/lib/themes/types.ts

@@ -0,0 +1,238 @@
+/**
+ * Theme System Type Definitions
+ *
+ * Compatible with AG Grid's Theming API structure
+ */
+
+// ============================================================================
+// THEME PARAMETERS
+// ============================================================================
+
+/**
+ * Theme configuration parameters
+ *
+ * All parameters are optional and can be overridden via withParams()
+ */
+export interface ThemeParameters {
+  // === Colors ===
+  /** Primary accent color for selections, highlights, etc. */
+  accentColor?: string;
+  /** Main background color */
+  backgroundColor?: string;
+  /** Main text/foreground color */
+  foregroundColor?: string;
+  /** Secondary text color (muted text) */
+  secondaryForegroundColor?: string;
+
+  // === Typography ===
+  /** Font family stack */
+  fontFamily?: string;
+  /** Base font size in pixels */
+  fontSize?: number;
+  /** Base font weight */
+  fontWeight?: number | 'normal' | 'bold' | 'lighter' | 'bolder';
+  /** Header font weight */
+  headerFontWeight?: number | 'normal' | 'bold' | 'lighter' | 'bolder';
+
+  // === Spacing ===
+  /** Base spacing unit in pixels */
+  spacing?: number;
+  /** Row height in pixels */
+  rowHeight?: number;
+  /** Header row height in pixels */
+  headerHeight?: number;
+  /** Cell padding in pixels */
+  cellPadding?: number;
+
+  // === Borders ===
+  /** Border color */
+  borderColor?: string;
+  /** Border width in pixels */
+  borderWidth?: number;
+  /** Border radius in pixels */
+  borderRadius?: number;
+
+  // === Specific Colors ===
+  /** Header background color */
+  headerBackgroundColor?: string;
+  /** Default row background color */
+  rowBackgroundColor?: string;
+  /** Even row background color (for striping) */
+  rowEvenBackgroundColor?: string;
+  /** Row background on hover */
+  rowHoverBackgroundColor?: string;
+  /** Row background when selected */
+  rowSelectedBackgroundColor?: string;
+  /** Cell background on hover */
+  cellHoverBackgroundColor?: string;
+
+  // === Group Row ===
+  /** Group row background color */
+  groupRowBackgroundColor?: string;
+  /** Group row indent width in pixels */
+  groupRowIndentWidth?: number;
+
+  // === Icons ===
+  /** Icon color */
+  iconColor?: string;
+  /** Icon size in pixels */
+  iconSize?: number;
+
+  // === Focus ===
+  /** Focus border color */
+  focusBorderColor?: string;
+  /** Focus border width */
+  focusBorderWidth?: number;
+}
+
+/**
+ * Partial theme parameters for overrides
+ */
+export type PartialThemeParameters = Partial<ThemeParameters>;
+
+// ============================================================================
+// THEME PARTS
+// ============================================================================
+
+/**
+ * Theme part type
+ * Parts are modular theme components that can be mixed and matched
+ */
+export type ThemePartType =
+  | 'color-scheme'
+  | 'icon-set'
+  | 'checkbox-style'
+  | 'input-style'
+  | 'tab-style'
+  | 'custom';
+
+/**
+ * Theme part configuration
+ */
+export interface ThemePart {
+  /** Part name/identifier */
+  name: string;
+  /** Part type */
+  type: ThemePartType;
+  /** CSS rules for this part */
+  css?: string;
+  /** Additional parameters this part uses */
+  additionalParams?: Record<string, any>;
+  /** Parameters this part overrides */
+  params?: PartialThemeParameters;
+}
+
+// ============================================================================
+// THEME OBJECT
+// ============================================================================
+
+/**
+ * Complete theme object
+ */
+export interface GridThemeObject {
+  /** Theme name */
+  name: string;
+  /** Theme description */
+  description?: string;
+  /** Theme parameters */
+  parameters: ThemeParameters;
+  /** Theme parts */
+  parts: ThemePart[];
+}
+
+/**
+ * Theme builder interface
+ * Used for chainable theme customization
+ */
+export interface ThemeBuilder {
+  /** Theme name */
+  readonly name: string;
+  /** Theme description */
+  readonly description?: string;
+  /** Theme parameters */
+  readonly parameters: ThemeParameters;
+  /** Theme parts */
+  readonly parts: ThemePart[];
+
+  /**
+   * Create a new theme with overridden parameters
+   */
+  withParams(params: PartialThemeParameters): ThemeBuilder;
+
+  /**
+   * Add a theme part to the theme
+   */
+  withPart(part: ThemePart): ThemeBuilder;
+
+  /**
+   * Get the final theme object
+   */
+  build(): GridThemeObject;
+
+  /**
+   * Convert theme to CSS custom properties
+   */
+  toCSS(): string;
+}
+
+// ============================================================================
+// COLOR SCHEMES
+// ============================================================================
+
+/**
+ * Predefined color scheme types
+ */
+export type ColorSchemeType = 'light' | 'dark' | 'auto';
+
+/**
+ * Color scheme part
+ */
+export interface ColorSchemePart extends ThemePart {
+  type: 'color-scheme';
+  scheme: ColorSchemeType;
+}
+
+// ============================================================================
+// ICON SETS
+// ============================================================================
+
+/**
+ * Predefined icon set types
+ */
+export type IconSetType = 'quartz' | 'material' | 'minimal' | 'custom';
+
+/**
+ * Icon definition
+ */
+export interface IconDefinition {
+  /** Icon name */
+  name: string;
+  /** Icon SVG path or URL */
+  path: string;
+  /** Icon viewBox */
+  viewBox?: string;
+}
+
+/**
+ * Icon set part
+ */
+export interface IconSetPart extends ThemePart {
+  type: 'icon-set';
+  icons: Record<string, IconDefinition>;
+}
+
+// ============================================================================
+// GRID OPTIONS INTEGRATION
+// ============================================================================
+
+/**
+ * Grid options theme configuration
+ */
+export interface ThemeGridOptions {
+  /** Theme object */
+  theme?: ThemeBuilder;
+  /** CSS layer name for theme styles */
+  themeCssLayer?: string;
+  /** Container element for theme styles */
+  themeStyleContainer?: HTMLElement | ShadowRoot | (() => HTMLElement | ShadowRoot);
+}