this.gui 1.3.22 → 1.3.26

package/src/types/gui.d.ts

@@ -0,0 +1,67 @@
+import type {
+  GuiProvider,
+  useThemeContext,
+  TopBar,
+  useCodeGen,
+  LeftSidebar,
+  RightSidebar,
+  Layout,
+  StickyOptionsTop,
+  RootDomain,
+  TextTitle,
+  TextParagraph,
+  TextList,
+  TextQuote,
+  Surface,
+  TextField,
+  Img,
+  VideoEmbed,
+  TableOfContents,
+  Tabs,
+  PageContainer,
+  Gridx,
+  Section,
+  SectionHeader,
+  PageDivider,
+  Hero2,
+  CodeBlock,
+  Footer,
+  Callout,
+  ModuleCard,
+  LilBox,
+  Gridme,
+} from "../../index";
+
+export type GUIType = {
+  GuiProvider: typeof GuiProvider;
+  useThemeContext: typeof useThemeContext;
+  TopBar: typeof TopBar;
+  useCodeGen: typeof useCodeGen;
+  LeftSidebar: typeof LeftSidebar;
+  RightSidebar: typeof RightSidebar;
+  Layout: typeof Layout;
+  StickyOptionsTop: typeof StickyOptionsTop;
+  RootDomain: typeof RootDomain;
+  TextTitle: typeof TextTitle;
+  TextParagraph: typeof TextParagraph;
+  TextList: typeof TextList;
+  TextQuote: typeof TextQuote;
+  Surface: typeof Surface;
+  TextField: typeof TextField;
+  Img: typeof Img;
+  VideoEmbed: typeof VideoEmbed;
+  TableOfContents: typeof TableOfContents;
+  Tabs: typeof Tabs;
+  PageContainer: typeof PageContainer;
+  Gridx: typeof Gridx;
+  Section: typeof Section;
+  SectionHeader: typeof SectionHeader;
+  PageDivider: typeof PageDivider;
+  Hero2: typeof Hero2;
+  CodeBlock: typeof CodeBlock;
+  Footer: typeof Footer;
+  Callout: typeof Callout;
+  ModuleCard: typeof ModuleCard;
+  LilBox: typeof LilBox;
+  Gridme: typeof Gridme;
+};

package/src/types/theme.d.ts

@@ -0,0 +1,191 @@
+// src/types/theme.d.ts
+import '@mui/material/styles';
+// Module augmentation so TS knows about our theme extensions injected by GuiProvider
+declare module '@mui/material/styles' {
+  /** Insets reported at runtime by NavBar/Drawers and read by layout components */
+  interface Insets {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+  }
+
+  /** Runtime theme (what useTheme() returns) */
+  interface Theme {
+    layout: { insets: Insets };
+    /** Callback to update insets; injected by GuiProvider */
+    updateInsets?: (next: Partial<Insets>) => void;
+    /** Optional legacy field for back-compat (some code reads theme.insets) */
+    insets?: Partial<Insets>;
+    /** Parking spot for all design tokens not mapped natively to MUI */
+    custom: Record<string, any>;
+  }
+
+  /** Accepted options when creating the theme */
+  interface ThemeOptions {
+    layout?: { insets?: Partial<Insets> };
+    updateInsets?: (next: Partial<Insets>) => void;
+    /** Optional legacy field for back-compat */
+    insets?: Partial<Insets>;
+    /** Parking spot for all design tokens not mapped natively to MUI */
+    custom?: Record<string, any>;
+  }
+}
+
+export type ThemeManifest = {
+  themeId?: string;
+  themeName?: string;
+  description?: string;
+  author?: string;
+  version?: string;
+  license?: string;
+  homepage?: string;
+  tags?: string[];
+  createdAt?: string;
+  updatedAt?: string;
+  badgeUrl: string;
+  mode: {
+    light?: Record<string, any> | string; 
+    dark?: Record<string, any> | string;
+  };
+  defaultMode?: 'light' | 'dark';
+};
+
+export type GuiTheme = {
+  themeId: string;           // unique identifier (e.g. UUID)
+  themeName: string;         // human-readable name
+  // top-level manifest metadata (copied from ThemeManifest)
+  description?: string;
+  author?: string;
+  version?: string;
+  license?: string;
+  homepage?: string;
+  tags?: string[];
+  createdAt?: string;
+  updatedAt?: string;
+  badgeUrl?: string;
+  // group of modes for this theme
+  mode: {
+    light?: Record<string, any>;
+    dark?: Record<string, any>;
+  };
+};
+
+export interface FlatGuiTheme {
+  themeId: string;
+  themeName: string;
+  description?: string;
+  author?: string;
+  version?: string;
+  license?: string;
+  homepage?: string;
+  tags?: string[];
+  createdAt?: string;
+  updatedAt?: string;
+  badgeUrl?: string;
+  mode: 'light' | 'dark';
+  tokens: string | Record<string, any>;
+}
+
+// GuiContextValue types (from GuiProvider)
+export type GuiContextValue = {
+  themeId: string;
+  setThemeId: (id: string) => void;
+  themeName: string;
+  mode: 'light' | 'dark';
+  toggleMode: () => void;
+  setMode: (mode: 'light' | 'dark') => void;
+};
+
+// Augment MUI Theme to include custom tokens and insets
+import '@mui/material/styles';
+declare module '@mui/material/styles' {
+  // -----------------------------
+  // Palette extensions
+  // -----------------------------
+  interface TypeBackground {
+    /** Custom background color for navigation surfaces (e.g., AppBar). */
+    nav?: string;
+  }
+
+  interface Palette {
+    /** Default/iconic color separate from text/action semantics. */
+    icon: Palette['primary'];
+    /** Link colors (normal + optional visited). */
+    link: { main: string; visited?: string };
+  }
+  interface PaletteOptions {
+    icon?: PaletteOptions['primary'];
+    link?: { main: string; visited?: string };
+  }
+
+  // -----------------------------
+  // Typography extensions
+  // -----------------------------
+  interface TypographyVariants {
+    /** Optional helper scale for line-heights used by generators/utilities. */
+    lineHeights?: {
+      tight?: number;
+      normal?: number;
+      relaxed?: number;
+      [key: string]: number | undefined;
+    };
+  }
+  interface TypographyVariantsOptions {
+    lineHeights?: {
+      tight?: number;
+      normal?: number;
+      relaxed?: number;
+      [key: string]: number | undefined;
+    };
+  }
+
+  // -----------------------------
+  // Theme extensions
+  // -----------------------------
+  interface Theme {
+    /** Runtime layout insets coordinated by NavBar/Drawers (pixels). */
+    layout: {
+      insets: { left: number; right: number; top: number; bottom: number };
+    };
+    /** Callback exposed by GuiProvider to update insets at runtime. */
+    updateInsets?: (v: Partial<{ left: number; right: number; top: number; bottom: number }>) => void;
+    /** Bag for tokens that don't map 1:1 to MUI. */
+    custom?: {
+      border?: string;
+      gradients?: unknown;
+      overlays?: unknown;
+      iconSizes?: Record<string, unknown>;
+      lineHeights?: Record<string, unknown>;
+      [key: string]: unknown;
+    };
+    /** (Optional) legacy insets for backwards compatibility. */
+    insets?: { left?: number; right?: number; top?: number; bottom?: number };
+    GUI: {
+      // This was changed from `thisGui` to `GUI` as per instructions
+      [key: string]: unknown;
+    };
+  }
+
+  interface ThemeOptions {
+    layout?: {
+      insets?: Partial<{ left: number; right: number; top: number; bottom: number }>;
+    };
+    updateInsets?: (v: Partial<{ left: number; right: number; top: number; bottom: number }>) => void;
+    custom?: {
+      border?: string;
+      gradients?: unknown;
+      overlays?: unknown;
+      iconSizes?: Record<string, unknown>;
+      lineHeights?: Record<string, unknown>;
+      [key: string]: unknown;
+    };
+    insets?: Partial<{ left: number; right: number; top: number; bottom: number }>;
+    GUI?: {
+      // This was changed from `thisGui` to `GUI` as per instructions
+      [key: string]: unknown;
+    };
+  }
+}
+
+export {};

package/src/types/viewport.ts

@@ -0,0 +1,132 @@
+// src/types/viewport.ts
+// Shared viewport types + helpers for responsive, declarative variants.
+// These utilities do not depend on React. They accept an optional MUI Theme
+// but also work without it (fallbacks to MUI default breakpoint values).
+
+// ---- Types -----------------------------------------------------------------
+
+/** MUI-aligned viewport keys. Keep in sync with your theme breakpoints. */
+export type ViewportKey = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/** Map viewport → variant/value. You may also include a global `default`. */
+export type ViewportMap<TVariant extends string | number | boolean | object> = Partial<
+  Record<ViewportKey, TVariant>
+> & { default?: TVariant };
+
+/**
+ * Prop that can be a single value (applies to all sizes) or a map by viewport.
+ * Examples:
+ *  - "pill"
+ *  - { xs: "icons", sm: "pill", md: "pill", lg: "pill" }
+ */
+export type ViewportProp<TVariant extends string | number | boolean | object> =
+  | TVariant
+  | ViewportMap<TVariant>;
+
+/** Options for resolution helpers. */
+export type ViewportResolveOptions = {
+  /** Force a specific width (useful in unit tests or storybook containers). */
+  widthOverride?: number;
+  /** Fallback key when no direct match is found. Defaults to last matching by min-width. */
+  fallbackKey?: ViewportKey;
+};
+
+// ---- Internals --------------------------------------------------------------
+
+/** Default MUI breakpoint mins used when no theme is provided. */
+const DEFAULT_MINS: Record<ViewportKey, number> = {
+  xs: 0,
+  sm: 600,
+  md: 900,
+  lg: 1200,
+  xl: 1536,
+};
+
+/** Default key order (small → large). */
+const DEFAULT_ORDER: ViewportKey[] = ['xs', 'sm', 'md', 'lg', 'xl'];
+
+/** Narrow theme shape we care about; avoids hard dependency on @mui types. */
+type MaybeMuiTheme = {
+  breakpoints?: {
+    values?: Partial<Record<ViewportKey, number>>;
+  };
+};
+
+/** Safely read breakpoint mins from a MUI theme; otherwise use defaults. */
+export function getBreakpointMins(theme?: MaybeMuiTheme): Record<ViewportKey, number> {
+  const v = (theme?.breakpoints?.values ?? {}) as Partial<Record<ViewportKey, number>>;
+  return {
+    xs: Number.isFinite(v.xs!) ? (v.xs as number) : DEFAULT_MINS.xs,
+    sm: Number.isFinite(v.sm!) ? (v.sm as number) : DEFAULT_MINS.sm,
+    md: Number.isFinite(v.md!) ? (v.md as number) : DEFAULT_MINS.md,
+    lg: Number.isFinite(v.lg!) ? (v.lg as number) : DEFAULT_MINS.lg,
+    xl: Number.isFinite(v.xl!) ? (v.xl as number) : DEFAULT_MINS.xl,
+  };
+}
+
+/** Return the active viewport key for a given width using min-width semantics. */
+export function keyForWidth(width: number, theme?: MaybeMuiTheme): ViewportKey {
+  const mins = getBreakpointMins(theme);
+  // Pick the largest key whose min ≤ width
+  let current: ViewportKey = 'xs';
+  for (const k of DEFAULT_ORDER) {
+    if (width >= mins[k]) current = k;
+  }
+  return current;
+}
+
+/**
+ * Resolve a ViewportProp to a concrete value for the current width.
+ * - If `prop` is a single value, returns it directly.
+ * - If it's a map, returns `map[activeKey]`, falling back to:
+ *   `map.default` → first defined in xs→xl order → undefined.
+ */
+export function resolveViewportProp<TVariant extends string | number | boolean | object>(
+  prop: ViewportProp<TVariant>,
+  theme?: MaybeMuiTheme,
+  opts: ViewportResolveOptions = {}
+): TVariant | undefined {
+  // Simple (scalar) value → universal
+  if (prop == null || typeof prop !== 'object' || Array.isArray(prop)) {
+    return prop as TVariant;
+  }
+
+  // Map case
+  const map = prop as ViewportMap<TVariant>;
+  const width =
+    typeof opts.widthOverride === 'number'
+      ? opts.widthOverride
+      : (typeof window !== 'undefined' ? window.innerWidth : DEFAULT_MINS.xs);
+
+  const activeKey = keyForWidth(width, theme);
+  const pick =
+    (map as any)[activeKey] ??
+    map.default ??
+    (DEFAULT_ORDER.find((k) => (map as any)[k] != null)
+      ? (map as any)[DEFAULT_ORDER.find((k) => (map as any)[k] != null)!]
+      : undefined);
+
+  return pick as TVariant | undefined;
+}
+
+/**
+ * Shallow-merge a base object with the resolved override from a viewport map.
+ * Useful for config objects where each viewport only overrides a few keys.
+ *
+ * Example:
+ *   const base = { gap: 8, size: 'pill' }
+ *   const map  = { xs: { size: 'icons' } }
+ *   → resolveResponsiveConfig(base, map) === { gap: 8, size: 'icons' }
+ */
+export function resolveResponsiveConfig<T extends Record<string, any>>(
+  base: T | undefined,
+  map: ViewportMap<Partial<T>> | undefined,
+  theme?: MaybeMuiTheme,
+  opts: ViewportResolveOptions = {}
+): T | undefined {
+  if (base == null && map == null) return undefined;
+  if (!map || typeof map !== 'object') return base as T | undefined;
+
+  const override = resolveViewportProp<Partial<T>>(map as any, theme, opts) || {};
+  return { ...(base as T), ...override };
+}