this.gui 1.0.18 → 1.1.0

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

@@ -0,0 +1,118 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Tooltip, Button, Typography } from '@/gui/atoms';
+
+const meta: Meta<typeof Tooltip> = {
+  title: 'Atoms/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/atoms/Tooltip/Tooltip.tsx

@@ -0,0 +1,78 @@
+/**
+ * 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/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 '../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;

package/src/gui/atoms/Typography/Typography.stories.tsx

@@ -0,0 +1,228 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+import Typography from './Typography';
+import Link from '../Link/Link';
+
+const meta = {
+  title: 'Atoms/Typography',
+  component: Typography,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 24 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**Typography** is a thin, polymorphic wrapper around MUI's Typography that keeps the full API
+while exposing it through This.GUI. Import it from **@/gui/primitives** instead of @mui/material so
+you can swap render engines in the future without breaking consumers.
+
+### Key points
+- Preserves MUI's polymorphism (\`component\`, \`as\`, \`variantMapping\`).
+- Works with routers and anchors: \`component={Link}\` + \`to\`, or \`component="a"\` + \`href\`.
+- Styled by your This.GUI theme (typography, palette, spacing).
+
+### Common variants
+MUI variants like \`h1..h6\`, \`subtitle1/2\`, \`body1/2\`, \`caption\`, \`overline\` are supported.
+
+### Declarative JSON example
+You can describe text nodes in JSON and hydrate them in a renderer:
+
+~~~json
+{
+  "type": "Typography",
+  "props": {
+    "variant": "h4",
+    "component": "h2",
+    "gutterBottom": true
+  },
+  "children": "Section Title"
+}
+~~~
+
+A naive hydration would look like:
+
+~~~tsx
+const spec = {
+  type: 'Typography',
+  props: { variant: 'h4', component: 'h2', gutterBottom: true },
+  children: 'Section Title'
+};
+
+<Typography {...spec.props}>{spec.children}</Typography>
+~~~
+        `,
+      },
+    },
+    controls: { exclude: ['component', 'to', 'href', 'variantMapping', 'ref'] },
+  },
+} satisfies Meta<typeof Typography>;
+
+export default meta;
+
+type Story = StoryObj<typeof Typography>;
+
+export const Basic: Story = {
+  args: {
+    variant: 'body1',
+    children: 'Hello from Typography',
+  },
+};
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gap: 8 }}>
+      <Typography variant="h1">h1. Heading</Typography>
+      <Typography variant="h2">h2. Heading</Typography>
+      <Typography variant="h3">h3. Heading</Typography>
+      <Typography variant="h4">h4. Heading</Typography>
+      <Typography variant="h5">h5. Heading</Typography>
+      <Typography variant="h6">h6. Heading</Typography>
+      <Typography variant="subtitle1">subtitle1</Typography>
+      <Typography variant="subtitle2">subtitle2</Typography>
+      <Typography variant="body1">body1</Typography>
+      <Typography variant="body2">body2</Typography>
+      <Typography variant="caption">caption</Typography>
+      <Typography variant="overline">overline</Typography>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Preview of common Material UI typography variants.'
+      }
+    }
+  }
+};
+
+export const AsPropAndGutter: Story = {
+  name: 'Semantic element (component) + gutter',
+  render: () => (
+    <div>
+      <Typography variant="h4" component="h2" gutterBottom>
+        Section title (rendered as h2)
+      </Typography>
+      <Typography variant="body1">
+        Body text below the title. The \`gutterBottom\` on the title adds spacing.
+      </Typography>
+    </div>
+  ),
+};
+
+export const Alignment: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gap: 8 }}>
+      <Typography align="left">Left aligned</Typography>
+      <Typography align="center">Center aligned</Typography>
+      <Typography align="right">Right aligned</Typography>
+    </div>
+  ),
+};
+
+export const Colors: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gap: 8 }}>
+      <Typography color="text.primary">text.primary</Typography>
+      <Typography color="text.secondary">text.secondary</Typography>
+      <Typography color="primary">primary</Typography>
+      <Typography color="#00aa96">#00aa96 (custom)</Typography>
+    </div>
+  ),
+};
+
+export const WithRouterAndAnchor: Story = {
+  name: 'Routing & anchors',
+  render: () => (
+    <div style={{ display: 'grid', gap: 12 }}>
+      {/* Router link (uses This.GUI Link under the hood) */}
+      <Typography component={Link as any} to="/docs" underline="none">
+        Go to /docs (Router link)
+      </Typography>
+
+      {/* External anchor */}
+      <Typography component="a" href="https://neurons.me" target="_blank" rel="noopener noreferrer">
+        Visit neurons.me (anchor)
+      </Typography>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates polymorphism: render as router link (with `to`) and as anchor (with `href`).'
+      }
+    }
+  }
+};
+
+export const VariantMappingOverride: Story = {
+  name: 'variantMapping override',
+  render: () => (
+    <div style={{ display: 'grid', gap: 8 }}>
+      <Typography
+        variant="subtitle1"
+        variantMapping={{ subtitle1: 'h3', body1: 'p' }}
+      >
+        subtitle1 text rendered as an H3 element via variantMapping
+      </Typography>
+      <Typography
+        variant="body1"
+        variantMapping={{ subtitle1: 'h3', body1: 'p' }}
+      >
+        body1 text rendered as a P element via variantMapping
+      </Typography>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'MUI Typography allows remapping variants to different HTML elements without changing visual style.'
+      }
+    }
+  }
+};
+
+export const DeclarativeSpec: Story = {
+  name: 'Declarative (JSON → Typography)',
+  render: () => {
+    const spec = {
+      type: 'Typography',
+      props: { variant: 'h5', component: 'h3', gutterBottom: true },
+      children: 'Declaratively rendered title',
+    } as const;
+
+    return (
+      <div style={{ display: 'grid', gap: 12 }}>
+        <pre style={{ background: 'rgba(127,127,127,0.08)', padding: 12, borderRadius: 8 }}>
+{`{
+  "type": "Typography",
+  "props": {
+    "variant": "h5",
+    "component": "h3",
+    "gutterBottom": true
+  },
+  "children": "Declaratively rendered title"
+}`}
+        </pre>
+        {/* naive renderer */}
+        <Typography {...spec.props}>{spec.children}</Typography>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Example of hydrating a Typography node from a JSON spec. In production, your app would use a central registry/renderer.'
+      }
+    }
+  }
+};

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

@@ -0,0 +1,27 @@
+/*
+ * This.GUI — Typography (polymorphic)
+ * Thin wrapper over MUI's Typography that preserves its full polymorphic API:
+ * - `component` / `as` (MUI OverridableComponent)
+ * - `variantMapping`
+ * - works with router links (`component={Link}`) or anchors (`component="a"`)
+ *
+ * Import from "@/gui/atoms" instead of "@mui/material" so we can change
+ * the underlying engine without breaking consumers.
+ */
+import * as React from 'react';
+import MuiTypography from '@mui/material/Typography';
+import type { OverridableComponent } from '@mui/material/OverridableComponent';
+import type { TypographyTypeMap } from '@mui/material/Typography';
+// Public prop type (mirrors MUI's polymorphic typing)
+export type TypographyProps = React.ComponentProps<
+  OverridableComponent<TypographyTypeMap<{}, 'span'>>
+>;
+// Component: preserve MUI OverridableComponent so `component` works as in MUI
+const Typography = MuiTypography as unknown as OverridableComponent<
+  TypographyTypeMap<{}, 'span'>
+>;
+// DevTools label
+(Typography as any).displayName = 'Gui.Typography';
+// Helpful alias for consumers who prefer a prefixed name
+export type GuiTypographyProps = TypographyProps;
+export default Typography;