this.gui 1.3.40 → 1.3.42

package/src/stories/Theme/ThemeViewer.stories.tsx

@@ -0,0 +1,91 @@
+/**
+ * ## Theme Viewer Story
+ *
+ * This story provides a live JSON visualization of your theme context and MUI theme.
+ *
+ * ### What you will see:
+ * - `mode`: Comes from your `ThemeContext`, shows if your theme is in `light` or `dark` mode.
+ * - `palette`: Full palette details from MUI's `createTheme`, including all primary/secondary colors, actions, background, etc.
+ * - `insets`: Comes from `InsetsContext`, gives layout-safe-area insets for notch-aware designs (top, right, bottom, left).
+ *
+ * ### Why use this?
+ * It’s useful for debugging:
+ * - If your theme is being applied correctly
+ * - How your layout adjusts with different inset values
+ * - How palettes resolve across modes
+ *
+ * Great for verifying dynamic theme changes or testing new color tokens.
+ */
+import type { Meta } from '@storybook/react';
+import { useTheme } from '@mui/material/styles';
+import { useThemeContext } from '@/gui/contexts/ThemeContext';
+import { useInsets } from '@/gui/hooks';
+
+/**
+ * Story: CurrentThemeState
+ *
+ * This Storybook story displays the current theme state injected via MUI's ThemeProvider
+ * along with custom context values such as `mode` (from ThemeContext) and `insets` (from InsetsContext).
+ *
+ * The output includes:
+ * - `mode`: Light/dark mode from the app's ThemeContext
+ * - `palette`: Full palette object from MUI's `createTheme`, including color tokens and UI actions
+ * - `insets`: Safe area insets (top/right/bottom/left) for layout padding/margin
+ *
+ * Useful for debugging how the current theme looks, understanding the applied color system,
+ * and ensuring injected context values are correctly picked up across the app.
+ */
+export const CurrentThemeState = () => {
+  const theme = useTheme();
+  const { mode, themeId } = useThemeContext();
+  const { insets } = useInsets();
+  return (
+    <pre style={{ padding: 16 }}>
+      <code>
+        {JSON.stringify(
+          {
+            mode,
+            themeId,
+            palette: theme.palette,
+            fontFamily: theme.typography?.fontFamily,
+            typography: theme.typography,
+            insets,
+          },
+          null,
+          2
+        )}
+      </code>
+    </pre>
+  );
+};
+
+export default {
+  title: 'Theme/Viewer',
+  component: CurrentThemeState,
+tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+This story renders the **active theme state** used throughout your app.
+
+### What you will see:
+- \`mode\`: Current light/dark mode from ThemeContext
+- \`palette\`: Full MUI palette object generated from createTheme(), including:
+  - primary, secondary, error, warning, success, info colors
+  - background and text colors
+  - action states (hover, focus, selected, etc.)
+- \`insets\`: Safe area layout padding (top/right/bottom/left) from InsetsContext (useful for notch-aware design)
+
+### Why this is useful:
+- Debug whether the correct theme is being used
+- Inspect how palette tokens resolve dynamically
+- Verify how inset values change (iOS, Android, desktop)
+- Helps debug dynamic theme toggles and token propagation
+
+Ideal for inspecting changes in real-time while modifying theme-related code or tokens.
+          `,
+      },
+    },
+  },
+} satisfies Meta<typeof CurrentThemeState>;

package/src/stories/Theme/Typography.stories.jsx

@@ -0,0 +1,211 @@
+// src/stories/Theme/Typography.stories.jsx
+import { Box, Typography, Paper, Divider, Stack, Chip } from '@mui/material';
+import { useTheme } from '@mui/material/styles';
+
+/**
+ * Small helper to render a sample block for a variant
+ */
+const TypeRow = ({ variant, sample = 'The quick brown fox jumps over the lazy dog 1234', extra }) => {
+  const theme = useTheme();
+  const v = theme.typography?.[variant] || {};
+  const lineHeight = typeof v.lineHeight === 'number' ? v.lineHeight : String(v.lineHeight || '');
+  const fontSize = v.fontSize || '';
+  const weight = v.fontWeight || '';
+
+  return (
+    <Paper
+      variant="outlined"
+      sx={{
+        p: 1.25,
+        borderColor: theme.custom?.border || theme.palette.divider,
+        bgcolor: 'background.paper',
+        minWidth: 280,
+        flex: '1 1 320px',
+      }}
+    >
+      <Typography variant="caption" sx={{ color: 'text.secondary', fontWeight: 700 }}>
+        {variant}
+      </Typography>
+      <Typography variant={variant} sx={{ mt: 0.5 }}>
+        {sample}
+      </Typography>
+      <Divider sx={{ my: 1 }} />
+      <Typography variant="caption" sx={{ color: 'text.secondary' }}>
+        <strong>font-size:</strong> {fontSize}{'  '}
+        <strong>line-height:</strong> {lineHeight}{'  '}
+        <strong>font-weight:</strong> {weight || '—'}
+        {extra ? <> · {extra}</> : null}
+      </Typography>
+    </Paper>
+  );
+};
+
+const Section = ({ title, hint, children }) => (
+  <Box sx={{ my: 3 }}>
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+      <Typography variant="h5" sx={{ fontWeight: 700 }}>
+        {title}
+      </Typography>
+      {hint ? <Chip size="small" label={hint} /> : null}
+    </Box>
+    <Divider sx={{ my: 1.5 }} />
+    {children}
+  </Box>
+);
+
+/**
+ * Preview of the main typography scale coming from the active theme.
+ * Uses whatever your token engine compiled into theme.typography.
+ */
+function TypographyScale() {
+  const theme = useTheme();
+
+  const variants = [
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'subtitle1',
+    'body1',
+    'body2',
+    'button',
+  ];
+
+  return (
+    <Box sx={{ p: 2, bgcolor: 'background.default', color: 'text.primary' }}>
+      <Section title="Font Family">
+        <Typography variant="body2">
+          <strong>theme.typography.fontFamily:</strong>{' '}
+          <code>{theme.typography?.fontFamily}</code>
+        </Typography>
+      </Section>
+
+      <Section title="Variants">
+        <Stack direction="row" spacing={1.25} useFlexGap flexWrap="wrap">
+          {variants.map((v) => (
+            <TypeRow key={v} variant={v} />
+          ))}
+        </Stack>
+      </Section>
+    </Box>
+  );
+}
+
+/**
+ * Extra details from tokens exposed in the runtime:
+ * - lineHeights scale (if defined in theme.typography.lineHeights)
+ * - weights (if your tokens encode them)
+ */
+function TypographyDetails() {
+  const theme = useTheme();
+  const lh = theme.typography?.lineHeights || {};
+  const weights = {
+    bold: theme.typography?.fontWeightBold,
+    medium: theme.typography?.fontWeightMedium,
+    regular: theme.typography?.fontWeightRegular,
+  };
+
+  return (
+    <Box sx={{ p: 2, bgcolor: 'background.default', color: 'text.primary' }}>
+      <Section title="Line Heights Scale" hint="From tokens → theme.typography.lineHeights">
+        {Object.keys(lh).length ? (
+          <Stack direction="row" spacing={1.25} useFlexGap flexWrap="wrap">
+            {Object.entries(lh).map(([k, v]) => (
+              <Paper
+                key={k}
+                variant="outlined"
+                sx={{
+                  p: 1.25,
+                  minWidth: 160,
+                  borderColor: theme.custom?.border || theme.palette.divider,
+                }}
+              >
+                <Typography variant="body2" sx={{ fontWeight: 700 }}>
+                  {k}
+                </Typography>
+                <Typography variant="caption" sx={{ color: 'text.secondary' }}>
+                  {String(v)}
+                </Typography>
+                <Divider sx={{ my: 1 }} />
+                <Typography sx={{ lineHeight: Number(v) || v }}>
+                  The quick brown fox jumps over the lazy dog.
+                </Typography>
+              </Paper>
+            ))}
+          </Stack>
+        ) : (
+          <Typography variant="body2" sx={{ color: 'text.secondary' }}>
+            No custom line height scale found in theme.typography.lineHeights.
+          </Typography>
+        )}
+      </Section>
+
+      <Section title="Font Weights (if provided)">
+        <Stack direction="row" spacing={1.25} useFlexGap flexWrap="wrap">
+          {Object.entries(weights).map(([k, v]) => (
+            <Paper
+              key={k}
+              variant="outlined"
+              sx={{
+                p: 1.25,
+                minWidth: 160,
+                borderColor: theme.custom?.border || theme.palette.divider,
+              }}
+            >
+              <Typography variant="body2" sx={{ fontWeight: 700 }}>
+                {k}
+              </Typography>
+              <Typography variant="caption" sx={{ color: 'text.secondary' }}>
+                {v ?? '—'}
+              </Typography>
+              <Divider sx={{ my: 1 }} />
+              <Typography sx={{ fontWeight: v ?? 600 }}>
+                The quick brown fox jumps over the lazy dog.
+              </Typography>
+            </Paper>
+          ))}
+        </Stack>
+      </Section>
+    </Box>
+  );
+}
+
+export default {
+  title: 'Theme/Typography',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Typography scale compiled from tokens. Shows font family, variant sizes/weights/line-height, and optional line-height scale & weights if your tokens expose them.',
+      },
+    },
+  },
+};
+
+export const Scale = {
+  name: 'Scale',
+  render: () => <TypographyScale />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Core typography variants from the active theme (h1–h5, subtitle1, body1, body2, button).',
+      },
+    },
+  },
+};
+
+export const Details = {
+  name: 'Details (Line Heights & Weights)',
+  render: () => <TypographyDetails />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Optional token-driven extras: line-height scale and font weights if present in the compiled theme.',
+      },
+    },
+  },
+};

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 };
+}