this.gui 1.3.24 → 1.3.26

package/src/gui/components/atoms/Tooltip/Tooltip.resolver.tsx

@@ -0,0 +1,142 @@
+import * as React from 'react';
+import Tooltip from './Tooltip';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+
+/**
+ * Tooltip — Resolver
+ * --------------------------------------------------
+ * Declarative spec → live <Tooltip /> with correct props.
+ * Supports nested declarative children via ctx.render when available.
+ */
+export type TooltipSpec = {
+  type: 'Tooltip';
+  props?: {
+    // Content
+    title?: React.ReactNode | string; // required by MUI; we default if missing
+    children?: React.ReactNode | any; // can be a nested spec object
+
+    // Behavior
+    placement?:
+      | 'bottom-end' | 'bottom-start' | 'bottom'
+      | 'left-end'   | 'left-start'   | 'left'
+      | 'right-end'  | 'right-start'  | 'right'
+      | 'top-end'    | 'top-start'    | 'top';
+    arrow?: boolean;
+    followCursor?: boolean;
+    enterDelay?: number;
+    enterNextDelay?: number;
+    enterTouchDelay?: number;
+    leaveDelay?: number;
+    leaveTouchDelay?: number;
+    disableFocusListener?: boolean;
+    disableHoverListener?: boolean;
+    disableInteractive?: boolean;
+    disableTouchListener?: boolean;
+    open?: boolean; // controlled mode
+
+    // Styling / test ids
+    sx?: SxProps<Theme>;
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+    'data-gui-id'?: string;
+  };
+};
+
+const TooltipResolver: RegistryEntry = {
+  type: 'Tooltip',
+  resolve(spec: TooltipSpec, ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const guiId = ensureNodeId('Tooltip', (p as any)['data-gui-id']);
+
+    // Resolve child: if a nested spec is provided and we have a renderer in ctx, use it.
+    let childCandidate: any = (spec.props?.children ?? (spec.props as any)?.child) as any;
+    if (!React.isValidElement(childCandidate) && childCandidate && typeof childCandidate === 'object' && ctx?.render) {
+      childCandidate = ctx.render(childCandidate);
+    }
+
+    // Tooltip expects exactly ONE ReactElement child. Coerce anything else into an element.
+    let childEl: React.ReactElement;
+    if (React.isValidElement(childCandidate)) {
+      childEl = childCandidate as React.ReactElement;
+    } else if (
+      typeof childCandidate === 'string' ||
+      typeof childCandidate === 'number' ||
+      typeof childCandidate === 'bigint'
+    ) {
+      childEl = <span>{String(childCandidate)}</span>;
+    } else if (childCandidate) {
+      // Arrays, iterables, true/false, portals, promises, etc. → wrap safely
+      childEl = <span>{childCandidate as any}</span>;
+    } else {
+      // No child provided → harmless inline element to satisfy MUI contract
+      childEl = <span style={{ display: 'inline-block', width: 0, height: 0 }} />;
+    }
+
+    let titleNode: React.ReactNode = p.title;
+    if (titleNode && !React.isValidElement(titleNode) && typeof titleNode === 'object' && ctx?.render) {
+      titleNode = ctx.render(titleNode as any);
+    }
+    if (typeof titleNode === 'undefined' || titleNode === null) {
+      titleNode = '';
+    }
+
+    const {
+      // remove resolver-only keys
+      id,
+      className,
+      sx,
+      placement,
+      arrow,
+      followCursor,
+      enterDelay,
+      enterNextDelay,
+      enterTouchDelay,
+      leaveDelay,
+      leaveTouchDelay,
+      disableFocusListener,
+      disableHoverListener,
+      disableInteractive,
+      disableTouchListener,
+      open,
+      // keep title out, we already computed titleNode
+      title: _title,
+      // also remove our custom id
+      ['data-gui-id']: _dataGuiId,
+      // and remove the alias 'child' if present
+      child: _child,
+      ...rest
+    } = p as any;
+
+    return (
+      <Tooltip
+        title={titleNode}
+        placement={placement}
+        arrow={arrow}
+        followCursor={followCursor}
+        enterDelay={enterDelay}
+        enterNextDelay={enterNextDelay}
+        enterTouchDelay={enterTouchDelay}
+        leaveDelay={leaveDelay}
+        leaveTouchDelay={leaveTouchDelay}
+        disableFocusListener={disableFocusListener}
+        disableHoverListener={disableHoverListener}
+        disableInteractive={disableInteractive}
+        disableTouchListener={disableTouchListener}
+        open={open}
+        sx={sx}
+        id={id}
+        className={className}
+        data-testid={(p as any)['data-testid']}
+        data-gui-id={guiId}
+        {...rest}
+      >
+        {childEl}
+      </Tooltip>
+    );
+  },
+};
+
+export default TooltipResolver;

package/src/gui/components/atoms/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,117 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Tooltip, Button, Typography } from '@/gui/components/atoms';
+
+const meta: Meta<typeof Tooltip> = {
+  title: 'Atoms/Content/Tooltip',
+  component: Tooltip,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "This Tooltip is a thin wrapper around MUI's Tooltip, supporting all MUI props and the `sx` prop for styling. Use it for helpful hover information, and configure it via JSON/config declaratively.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Tooltip>;
+
+export const Playground: Story = {
+  args: {
+    title: 'Tooltip text',
+    placement: 'top',
+    arrow: false,
+    size: 'md',
+    children: <Button variant="contained">Hover me</Button>,
+  },
+  argTypes: {
+    title: { control: 'text' },
+    placement: {
+      control: 'select',
+      options: ['top', 'bottom', 'left', 'right'],
+    },
+    arrow: { control: 'boolean' },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+    },
+  },
+  render: (args) => <Tooltip {...args} size={args.size}>{args.children}</Tooltip>,
+};
+
+export const PlacementRight: Story = {
+  name: 'Placement: right',
+  render: () => (
+    <Tooltip title="Right placed tooltip" placement="right">
+      <Button variant="contained">Hover right</Button>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip with `placement="right"` demonstrates MUI placement support.',
+      },
+    },
+  },
+};
+
+export const WithArrow: Story = {
+  name: 'Arrow',
+  render: () => (
+    <Tooltip title="Tooltip with arrow" arrow>
+      <Button variant="contained">Hover arrow</Button>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip with `arrow={true}` prop shows the arrow, just like MUI.',
+      },
+    },
+  },
+};
+
+export const WithTypography: Story = {
+  name: 'Wrapped Typography',
+  render: () => (
+    <Tooltip title="Tooltip on text">
+      <Typography variant="body1" sx={{ cursor: 'pointer', display: 'inline-block' }}>
+        Hover this text
+      </Typography>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip wrapping a Typography element, showing flexibility and full MUI compatibility.',
+      },
+    },
+  },
+};
+
+
+export const WithSize: Story = {
+  name: 'With Size',
+  render: () => (
+    <div style={{ display: 'flex', gap: 24 }}>
+      <Tooltip title="Small size tooltip" size="sm">
+        <Button variant="contained">Small (sm)</Button>
+      </Tooltip>
+      <Tooltip title="Medium size tooltip" size="md">
+        <Button variant="contained">Medium (md)</Button>
+      </Tooltip>
+      <Tooltip title="Large size tooltip" size="lg">
+        <Button variant="contained">Large (lg)</Button>
+      </Tooltip>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates the Tooltip with different `size` props: small, medium, and large.',
+      },
+    },
+  },
+};

package/src/gui/components/atoms/Tooltip/Tooltip.tsx

@@ -0,0 +1,70 @@
+/**
+ * This.GUI — Tooltip (atom)
+ * Thin wrapper around MUI's Tooltip that keeps a stable import path:
+ *   import { Tooltip } from '@/gui/atoms'
+ *
+ * Extensions:
+ * - Adds an optional `size` prop (`'sm' | 'md' | 'lg' | 'xl'`) to scale typography/padding/arrow.
+ * - Still allows granular overrides via `slotProps.tooltip.sx` and `slotProps.arrow.sx`
+ *   which take precedence (our size styles are merged first).
+ *
+ * Notes:
+ * - Tooltip is NOT polymorphic (no `component` prop).
+ * - Works seamlessly with This.GUI theme through GuiProvider.
+ *
+ * Examples:
+ *   <Tooltip title="Hello"><Button>Hover me</Button></Tooltip>
+ *   <Tooltip title="Info" size="lg" arrow placement="right" slotProps={{ tooltip: { sx: { bgcolor: 'primary.main' } } }}>
+ *     <IconButton><Icon name="mui:Info" /></IconButton>
+ *   </Tooltip>
+ */
+import * as React from 'react';
+import MuiTooltip, { type TooltipProps as MuiTooltipProps } from '@mui/material/Tooltip';
+export type TooltipSize = 'sm' | 'md' | 'lg' | 'xl';
+export type TooltipProps = Omit<MuiTooltipProps, 'slotProps'> & {
+  /**
+   * Visual size of the tooltip bubble (typography + padding + arrow).
+   * This is a This.GUI extension; if omitted, MUI defaults are used.
+   */
+  size?: TooltipSize;
+  /**
+   * Keep MUI slotProps but allow merging with size presets.
+   * User-provided sx is applied AFTER our size preset, so it wins.
+   */
+  slotProps?: MuiTooltipProps['slotProps'];
+};
+
+const SIZE_PRESETS: Record<TooltipSize, { tooltipSx: any; arrowSx: any }> = {
+  sm: { tooltipSx: { fontSize: 11, p: '4px 8px' },  arrowSx: { fontSize: 10 } },
+  md: { tooltipSx: { fontSize: 13, p: '6px 10px' }, arrowSx: { fontSize: 12 } },
+  lg: { tooltipSx: { fontSize: 15, p: '8px 12px' }, arrowSx: { fontSize: 14 } },
+  xl: { tooltipSx: { fontSize: 17, p: '10px 14px' }, arrowSx: { fontSize: 16 } },
+};
+
+const Tooltip = React.forwardRef<HTMLDivElement, TooltipProps>(function Tooltip(props, ref) {
+  const { size, slotProps, ...rest } = props;
+  // Build merged slotProps so consumer overrides win
+  const preset = size ? SIZE_PRESETS[size] : undefined;
+  const mergedSlotProps = React.useMemo<any>(() => {
+    if (!preset) return slotProps;
+    const next = { ...slotProps };
+    // Tooltip content
+    next.tooltip = {
+      ...(slotProps?.tooltip as any),
+      // Ensure `sx` is an array so both apply; user-provided last wins.
+      sx: [preset.tooltipSx, (slotProps?.tooltip as any)?.sx].filter(Boolean) as any,
+    } as any;
+    // Arrow (applies only if `arrow` prop is set, but harmless to keep)
+    next.arrow = {
+      ...(slotProps?.arrow as any),
+      sx: [preset.arrowSx, (slotProps?.arrow as any)?.sx].filter(Boolean) as any,
+    } as any;
+    return next;
+  }, [preset, slotProps]);
+
+  return <MuiTooltip ref={ref} slotProps={mergedSlotProps} {...rest} />;
+});
+
+(Tooltip as any).displayName = 'Gui.Tooltip';
+export default Tooltip;
+export type { TooltipProps as GuiTooltipProps };

package/src/gui/components/atoms/Typography/Typography.resolver.tsx

@@ -0,0 +1,158 @@
+// src/gui/atoms/Typography/Typography.resolver.tsx
+import * as React from 'react';
+import Typography from './Typography';
+import Link from '@/gui/components/atoms/Link/Link';
+import type { RegistryEntry } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative spec for Typography
+ * - JSON-friendly: prefer `to` / `href` / `external` over `component`.
+ * - React usage: `component` may be a real React element type (Link, etc.).
+ * - A `data-gui-id` is attached automatically for stable editor/node identification.
+ */
+type TypographySpec = {
+  type: 'Typography';
+  props?: {
+    // Content
+    text?: React.ReactNode;            // convenience for simple text
+    children?: React.ReactNode;        // explicit children wins over `text`
+
+    // Core MUI props (subset; rest are passthrough)
+    variant?:
+      | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+      | 'subtitle1' | 'subtitle2'
+      | 'body1' | 'body2'
+      | 'caption' | 'overline'
+      | 'button';
+    align?: 'inherit' | 'left' | 'center' | 'right' | 'justify';
+    paragraph?: boolean;
+    gutterBottom?: boolean;
+    noWrap?: boolean;
+    color?: any;
+    variantMapping?: Record<string, React.ElementType>;
+
+    // Polymorphism / routing
+    component?: any;                   // React-only; ignored if a plain string (except 'a')
+    as?: any;                          // alias of component
+    to?: string;                       // SPA routing (resolver defaults to This.GUI Link)
+    href?: string;                     // anchor target
+    external?: boolean;                // if true → anchor + safe target/rel
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+
+    // Styling / misc
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+/**
+ * TypographyResolver
+ * - Maps JSON-friendly spec → real <Typography /> props.
+ * - If `to` is present (and no explicit component), defaults to This.GUI `Link`.
+ * - If `external` is true, or `href` is provided (and no explicit component), renders an anchor.
+ * - Never leaks `to`/`href` to invalid targets.
+ * - A `data-gui-id` is attached automatically for stable editor/node identification.
+ */
+const TypographyResolver: RegistryEntry = {
+  type: 'Typography',
+  resolve(spec: TypographySpec) {
+    const p = spec.props ?? {};
+
+    // Stable editor/node id (does not collide with user's `id`)
+    const guiId = ensureNodeId('Typography', (p as any)['data-gui-id']);
+
+    // Resolve a safe component:
+    // - accept real React element types/functions (React usage)
+    // - allow intrinsic 'a' (string) explicitly
+    // - ignore other strings coming from JSON (e.g. "Link")
+    const rawComp = p.component ?? p.as;
+    const safeFromReact =
+      typeof rawComp === 'function' ? rawComp
+      : undefined;
+    const allowedIntrinsic = rawComp === 'a' ? 'a' : undefined;
+
+    let component: any = safeFromReact ?? allowedIntrinsic ?? undefined;
+
+    // Build routing props carefully, only when target supports them
+    const extraProps: Record<string, any> = {};
+
+    if (p.external) {
+      // External anchors always render as <a>
+      if (!component) component = 'a';
+      if (component === 'a') {
+        extraProps.href = p.href;
+        extraProps.target = p.target ?? '_blank';
+        extraProps.rel = p.rel ?? 'noopener noreferrer';
+      }
+    } else if (p.to && !component) {
+      // SPA routing by default uses our Link
+      component = Link;
+      extraProps.to = p.to;
+    } else if (p.href && !component) {
+      // Plain anchors (non-external)
+      component = 'a';
+      extraProps.href = p.href;
+      if (p.target) extraProps.target = p.target;
+      if (p.rel) extraProps.rel = p.rel;
+    } else {
+      // If user passed a real Link component explicitly, wire `to`
+      if (component === Link && p.to) {
+        extraProps.to = p.to;
+      }
+      // If user passed 'a', wire `href`/`target`/`rel`
+      if (component === 'a' && (p.href || p.target || p.rel)) {
+        if (p.href) extraProps.href = p.href;
+        if (p.target) extraProps.target = p.target;
+        if (p.rel) extraProps.rel = p.rel;
+      }
+      // Otherwise do not leak `to`/`href` to invalid DOM nodes
+    }
+
+    // Children precedence: explicit children > text > empty
+    const children = p.children ?? p.text ?? null;
+
+    // Strip resolver-only fields so they don't end up as DOM attributes
+    const {
+      text: _text,
+      as: _as,
+      external: _external,
+      to: _to,
+      href: _href,
+      target: _target,
+      rel: _rel,
+      ...rest
+    } = p;
+
+    return (
+      <Typography
+        component={component}
+        variant={p.variant}
+        align={p.align}
+        paragraph={p.paragraph}
+        gutterBottom={p.gutterBottom}
+        noWrap={p.noWrap}
+        color={p.color}
+        variantMapping={p.variantMapping}
+        sx={p.sx}
+        className={p.className}
+        id={p.id}
+        data-testid={p['data-testid']}
+        data-gui-id={guiId}
+        {...extraProps}
+        {...rest}
+      >
+        {children}
+      </Typography>
+    );
+  },
+};
+
+export default TypographyResolver;