this.gui 1.0.17 → 1.1.0

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

@@ -0,0 +1,242 @@
+// src/gui/atoms/Switch/Switch.stories.tsx
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { MemoryRouter } from 'react-router-dom';
+import { Box, Stack, Typography, Switch } from '@/gui/atoms';
+import { FormControlLabel } from '@mui/material';
+import GuiProvider from '@/context/GuiProvider';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Switch> = {
+  title: 'Atoms/Switch',
+  component: Switch,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <Box sx={{ p: 2 }}>
+            <Story />
+          </Box>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**Switch (This.GUI atom)** is a thin wrapper around MUI's \`Switch\`.
+It keeps MUI behavior, styling, and typing, but you import it from \`@/gui/atoms\` to keep your app decoupled from MUI.
+
+---
+
+# Usage
+
+## React (imperative)
+~~~tsx
+import { Switch } from '@/gui/atoms';
+
+export function Example() {
+  const [enabled, setEnabled] = React.useState(false);
+  return (
+    <Switch
+      checked={enabled}
+      onChange={(_, v) => setEnabled(v)}
+      color="primary"
+      size="medium"
+    />
+  );
+}
+~~~
+
+With an accessible label (MUI way):
+~~~tsx
+import { FormControlLabel } from '@mui/material';
+
+<FormControlLabel control={<Switch defaultChecked />} label="Enable notifications" />
+~~~
+
+---
+
+## Declarative (resolver)
+If you’re rendering via a JSON/registry resolver, you can pass the same props:
+
+~~~json
+{
+  "type": "Switch",
+  "props": {
+    "label": "Enable feature",
+    "defaultChecked": true,
+    "color": "primary",
+    "size": "small",
+    "id": "feat-toggle",
+    "sx": { "ml": 1 }
+  }
+}
+~~~
+
+The resolver supports:
+- All native MUI Switch props (\`checked\`, \`defaultChecked\`, \`onChange\`, \`color\`, \`size\`, \`disabled\`, \`edge\`, \`inputProps\`, \`sx\`, etc.).
+- \`label?: ReactNode\` and \`labelPlacement?: 'start' | 'end' | 'top' | 'bottom'\` (wraps in \`FormControlLabel\` when present).
+- \`id\`, \`className\`, \`data-testid\` passthrough for testing and DOM hooks.
+
+---
+        `,
+      },
+    },
+  },
+  argTypes: {
+    checked: {
+      control: 'boolean',
+      description: 'Controlled state. Use with onChange.',
+      table: { category: 'Behavior' },
+    },
+    defaultChecked: {
+      control: 'boolean',
+      description: 'Uncontrolled initial state.',
+      table: { category: 'Behavior' },
+    },
+    disabled: {
+      control: 'boolean',
+      table: { category: 'Behavior' },
+    },
+    color: {
+      control: 'select',
+      options: ['primary', 'secondary', 'default'],
+      table: { category: 'Appearance' },
+    },
+    size: {
+      control: 'radio',
+      options: ['small', 'medium'],
+      description: 'Same as MUI Switch (no large by default).',
+      table: { category: 'Appearance' },
+    },
+    edge: {
+      control: 'radio',
+      options: [false, 'start', 'end'],
+      table: { category: 'Appearance' },
+    },
+    sx: { table: { category: 'Style' } },
+    id: { table: { category: 'DOM' } },
+    className: { table: { category: 'DOM' } },
+    // Not useful to control live in SB
+    onChange: { table: { disable: true } },
+    inputProps: { table: { disable: true } },
+  },
+  args: {
+    defaultChecked: false,
+    color: 'primary',
+    size: 'medium',
+    edge: false,
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Switch>;
+
+// ======================= Stories =======================
+
+export const Playground: Story = {
+  render: (args) => <Switch {...args} />,
+};
+
+export const LabeledVariants: Story = {
+  name: 'With label & placement',
+  render: () => (
+    <Stack spacing={2}>
+      <FormControlLabel control={<Switch defaultChecked />} label="End (default)" />
+      <FormControlLabel control={<Switch defaultChecked />} label="Start" labelPlacement="start" />
+      <FormControlLabel control={<Switch />} label="Top" labelPlacement="top" />
+      <FormControlLabel control={<Switch />} label="Bottom" labelPlacement="bottom" />
+    </Stack>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'When `label` is present, the atom wraps the control with `FormControlLabel`. Use `labelPlacement` to position it.',
+      },
+    },
+  },
+};
+
+export const SizesAndColors: Story = {
+  name: 'Sizes & colors',
+  render: () => (
+    <Stack spacing={2}>
+      <Stack direction="row" spacing={2} alignItems="center">
+        <Typography variant="body2" sx={{ minWidth: 88 }}>small</Typography>
+        <Switch size="small" color="default" defaultChecked />
+        <Switch size="small" color="primary" defaultChecked />
+        <Switch size="small" color="secondary" defaultChecked />
+      </Stack>
+      <Stack direction="row" spacing={2} alignItems="center">
+        <Typography variant="body2" sx={{ minWidth: 88 }}>medium</Typography>
+        <Switch size="medium" color="default" defaultChecked />
+        <Switch size="medium" color="primary" defaultChecked />
+        <Switch size="medium" color="secondary" defaultChecked />
+      </Stack>
+    </Stack>
+  ),
+};
+
+export const ControlledExample: Story = {
+  name: 'Controlled (React state)',
+  render: () => {
+    const [on, setOn] = React.useState(false);
+    return (
+      <Stack spacing={1.5}>
+        <Typography variant="body2">Value: <b>{on ? 'true' : 'false'}</b></Typography>
+        <FormControlLabel
+          control={
+            <Switch
+              checked={on}
+              onChange={(_, v) => setOn(v)}
+              color={on ? 'primary' : 'secondary'}
+            />
+          }
+          label="Controlled switch"
+        />
+      </Stack>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Classic controlled pattern: bind `checked` and update via `onChange`. You can also change appearance based on state.',
+      },
+    },
+  },
+};
+
+export const EdgeAndSx: Story = {
+  name: 'Edge & custom sx',
+  render: () => (
+    <Stack spacing={2}>
+      <FormControlLabel control={<Switch edge="start" defaultChecked />} label="Edge start" />
+      <FormControlLabel
+        control={
+          <Switch
+            defaultChecked
+            sx={{
+              '& .MuiSwitch-switchBase.Mui-checked + .MuiSwitch-track': {
+                opacity: 0.7,
+              },
+            }}
+          />
+        }
+        label="Custom sx"
+      />
+    </Stack>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass any `sx` overrides exactly as you would with MUI. Useful for fine-grained tuning without creating a new variant.',
+      },
+    },
+  },
+};

package/src/gui/atoms/Switch/Switch.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import MuiSwitch from '@mui/material/Switch';
+import type { SwitchProps as MuiSwitchProps } from '@mui/material/Switch';
+/**
+ * Switch (This.GUI primitive)
+ * ----------------------------------------
+ * Thin wrapper over MUI's `Switch`.
+ * - Non‑polymorphic (same as MUI): forwards ref to the root element.
+ * - Preserves all MUI props (`checked`, `onChange`, `size`, `color`, etc.).
+ *
+ * Usage:
+ *   import { Switch } from '@/gui/atoms';
+ *   <Switch checked={on} onChange={(e) => setOn(e.target.checked)} size="small" />
+ */
+
+// Re-export MUI's prop types so consumers can import from our surface.
+export type SwitchProps = MuiSwitchProps;
+const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(function Switch(props, ref) {
+  return <MuiSwitch ref={ref} {...props} />;
+});
+export default Switch;
+export type { MuiSwitchProps };

package/src/gui/atoms/Toolbar/Toolbar.resolver.tsx

@@ -0,0 +1,60 @@
+// src/gui/atoms/Toolbar/Toolbar.resolver.tsx
+import * as React from 'react';
+import Toolbar from './Toolbar';
+import type { RegistryEntry } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+type ToolbarSpec = {
+  type: 'Toolbar';
+  props?: {
+    /** Children content (text or nodes) */
+    children?: React.ReactNode;
+
+    /** MUI props */
+    variant?: 'regular' | 'dense';
+    disableGutters?: boolean;
+
+    /** Styling / misc */
+    sx?: SxProps<Theme>;
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+  };
+};
+
+/**
+ * ToolbarResolver
+ * - Maps JSON-friendly spec → <Toolbar /> props.
+ * - Accepts sx/id/className for styling and test hooks.
+ */
+const ToolbarResolver: RegistryEntry = {
+  type: 'Toolbar',
+  resolve(spec: ToolbarSpec) {
+    const p = spec.props ?? {};
+    const {
+      children,
+      variant,
+      disableGutters,
+      sx,
+      className,
+    } = p;
+
+    const id = ensureNodeId('Toolbar', p.id);
+
+    return (
+      <Toolbar
+        variant={variant}
+        disableGutters={disableGutters}
+        sx={sx}
+        id={id}
+        className={className}
+        data-testid={p['data-testid']}
+      >
+        {children}
+      </Toolbar>
+    );
+  },
+};
+
+export default ToolbarResolver;

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

@@ -0,0 +1,163 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+
+// Atoms used in the examples
+import { Toolbar, AppBar, Box, IconButton, Typography, Button } from '@/gui/atoms';
+import Icon from '@/themes/icons/Icon';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Toolbar> = {
+  title: 'Atoms/Toolbar',
+  component: Toolbar,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 240 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Toolbar** atom is a thin wrapper over MUI's \`MuiToolbar\`.
+
+> **Not polymorphic.** Unlike \`Button\` or \`Box\`, **Toolbar does not accept** a \`component\` prop in MUI. If you need a different semantic element (e.g. \`<header>\`), wrap it with \`<Box component="header">\`.
+
+---
+## Features
+- Density via \`variant\`: \`'regular'\` | \`'dense'\`.
+- Optional gutters removal with \`disableGutters\`.
+- Full **\`sx\`** support for styling.
+- Plays nicely inside **AppBar** and custom layouts.
+
+---
+## Key Props
+- \`variant?: 'regular' | 'dense'\`
+- \`disableGutters?: boolean\`
+- \`sx?: SxProps\` — theme-aware styling.
+
+---
+## Basic usage
+~~~tsx
+import { Toolbar } from '@/gui/atoms';
+
+<Toolbar>
+  <span>Left content</span>
+</Toolbar>
+~~~
+
+## In an AppBar
+~~~tsx
+import { AppBar, Toolbar, Typography } from '@/gui/atoms';
+
+<AppBar position="static">
+  <Toolbar>
+    <Typography variant="h6">Title</Typography>
+  </Toolbar>
+</AppBar>
+~~~
+
+## Change semantic element with Box
+~~~tsx
+import { Box, Toolbar } from '@/gui/atoms';
+
+<Box component="header">
+  <Toolbar variant="dense">Compact header</Toolbar>
+</Box>
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component']
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['regular', 'dense'],
+    },
+    disableGutters: { control: 'boolean' },
+    // Toolbar is not polymorphic in MUI, so hide any notion of `component`
+  },
+  args: {
+    variant: 'regular',
+    disableGutters: false,
+    children: (
+      <div style={{ display: 'flex', width: '100%', alignItems: 'center', gap: 12 }}>
+        <strong>Toolbar content</strong>
+      </div>
+    ),
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Toolbar>;
+
+// ======================= Stories =======================
+export const Playground: Story = {};
+
+export const DenseVsRegular: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gap: 12 }}>
+      <Toolbar>
+        <Typography variant="body2">Regular Toolbar</Typography>
+      </Toolbar>
+      <Toolbar variant="dense">
+        <Typography variant="body2">Dense Toolbar</Typography>
+      </Toolbar>
+    </div>
+  ),
+};
+
+export const WithActions: Story = {
+  render: () => (
+    <Toolbar sx={{ display: 'flex', gap: 8 }}>
+      <Typography sx={{ flex: 1 }} variant="h6">Title</Typography>
+      <IconButton aria-label="search">
+        <Icon name="lucide:Search" size={20} />
+      </IconButton>
+      <IconButton aria-label="user">
+        <Icon name="lucide:user" size={20} />
+      </IconButton>
+      <Button variant="contained" size="small">Action</Button>
+    </Toolbar>
+  ),
+};
+
+export const InAppBar: Story = {
+  render: () => (
+    <AppBar position="static">
+      <Toolbar>
+        <Typography variant="h6" sx={{ flex: 1 }}>App Bar + Toolbar</Typography>
+        <Button color="inherit" size="small">Login</Button>
+      </Toolbar>
+    </AppBar>
+  ),
+};
+
+export const WrappedInHeader: Story = {
+  render: () => (
+    <Box component="header" sx={{ border: '1px solid', borderColor: 'divider' }}>
+      <Toolbar variant="dense">
+        <Typography variant="body2">Header Toolbar (wrapped by Box)</Typography>
+      </Toolbar>
+    </Box>
+  ),
+};
+
+export const WithCustomSx: Story = {
+  render: () => (
+    <Toolbar sx={{ bgcolor: 'background.paper', border: '1px dashed', borderColor: 'divider', borderRadius: 1 }}>
+      <Typography variant="body2">Styled with sx</Typography>
+    </Toolbar>
+  ),
+};

package/src/gui/atoms/Toolbar/Toolbar.tsx

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import MuiToolbar from '@mui/material/Toolbar';
+/**
+ * This.GUI — Toolbar atom
+ * Thin wrapper around MUI's Toolbar so consumers import from "@/gui/atoms"
+ * instead of "@mui/material". This keeps the engine swappable.
+ *
+ * Notes:
+ * - We type props from MuiToolbar to preserve its full API (incl. `component`, `sx`, etc.).
+ * - Ref is HTMLDivElement, matching the default DOM element Toolbar renders.
+ */
+export type ToolbarProps = React.ComponentProps<typeof MuiToolbar>;
+const Toolbar = React.forwardRef<HTMLDivElement, ToolbarProps>(function Toolbar(props, ref) {
+  return <MuiToolbar ref={ref} {...props} />;});
+(Toolbar as any).displayName = 'Gui.Toolbar';
+export default Toolbar;

package/src/gui/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;