this.gui 1.0.18 → 1.1.0

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

@@ -0,0 +1,225 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button, Link } from '@/gui/atoms';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+
+// ======================= Meta =======================
+const meta: Meta<typeof Button> = {
+  title: 'Atoms/Button',
+  component: Button,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 240 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Button** primitive is a thin wrapper around MUI's \`MuiButton\` that preserves **polymorphism** and adds **declarative icons** (string tokens like 
+\`mui:Send\` or \`lucide:bolt\`). It integrates with **This.GUI** theming and respects your token-built palette.
+
+---
+## Features
+- Variants: \`contained\`, \`outlined\`, \`text\`.
+- Colors: \`primary\`, \`secondary\`, \`success\`, \`info\`, \`warning\`, \`error\`, \`inherit\`.
+- Sizes: \`small\`, \`medium\`, \`large\`.
+- **Icons** via tokens (\`startIcon\` / \`endIcon\`) or React nodes.
+- **Polymorphic**: \`component\` can be \`'a'\` or a Link (e.g. the This.GUI wrapper \`Link\`) for routing.
+- Respects your theme from \`GuiProvider\` (no need to wrap with \`ThemeProvider\`).
+
+---
+## Key Props
+- \`startIcon?: string | ReactNode\` — accepts a name from the **icon registry** (\`mui:*\` / \`lucide:*\`) or a React element.
+- \`endIcon?: string | ReactNode\`.
+- \`component?: ElementType | string\` — for polymorphism (\`'a'\`, RouterLink, etc.).
+- \`href?: string\` — when \`component='a'\`.
+- \`to?: string\` — when \`component={Link}\`.
+
+> Note: \`to\` and \`href\` are not exposed as Storybook controls because they only apply in specific modes; they are shown in dedicated stories.
+
+---
+## Basic usage
+~~~jsx
+import { Button } from '@/gui/primitives';
+
+<Button variant="contained" color="primary">Save</Button>
+<Button variant="outlined" color="secondary">Cancel</Button>
+<Button variant="text">Learn more</Button>
+~~~
+
+## With declarative icons
+~~~jsx
+<Button variant="contained" color="secondary" startIcon="mui:Send" endIcon="lucide:bolt">
+  Send
+</Button>
+~~~
+
+## As native anchor link
+~~~jsx
+<Button component="a" href="https://neurons.me" /* target="_blank" rel="noreferrer" */>
+  Visit neurons.me
+</Button>
+~~~
+
+## With RouterLink (This.GUI Link)
+~~~jsx
+import { Button, Link } from '@/gui/primitives';
+
+<Button component={Link} to="/docs">Go to docs</Button>
+~~~
+## Declarative JSON / Config usage
+~~~json
+{
+  "type": "Button",
+  "props": {
+    "variant": "text",
+    "color": "primary",
+    "component": "a",
+    "href": "https://neurons.me",
+    "target": "_blank",
+    "rel": "noreferrer",
+    "children": "Visit neurons.me"
+  }
+}
+~~~
+
+Another example with a RouterLink:
+~~~json
+{
+  "type": "Button",
+  "props": {
+    "variant": "contained",
+    "color": "secondary",
+    "component": "Link",
+    "to": "/docs",
+    "startIcon": "mui:Send",
+    "children": "Go to docs"
+  }
+}
+~~~
+        `,
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['contained', 'outlined', 'text'],
+    },
+    color: {
+      control: { type: 'select' },
+      options: ['primary', 'secondary', 'success', 'info', 'warning', 'error', 'inherit'],
+    },
+    size: {
+      control: { type: 'radio' },
+      options: ['small', 'medium', 'large'],
+    },
+    startIcon: { control: 'text', description: 'Icon token or a React element.' },
+    endIcon: { control: 'text', description: 'Icon token or a React element.' },
+    onClick: { action: 'clicked' },
+  },
+  args: {
+    variant: 'contained',
+    color: 'primary',
+    size: 'medium',
+    children: 'Click me',
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Button>;
+
+// ======================= Stories =======================
+export const Playground: Story = {};
+
+export const Variants: Story = {
+  args: { color: 'primary' },
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+      <Button {...args} variant="contained">Contained</Button>
+      <Button {...args} variant="outlined">Outlined</Button>
+      <Button {...args} variant="text">Text</Button>
+    </div>
+  ),
+};
+
+export const Colors: Story = {
+  args: { variant: 'contained' },
+  render: (args) => {
+    const colors: Array<'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error'> =
+      ['primary', 'secondary', 'success', 'info', 'warning', 'error'];
+    return (
+      <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+        {colors.map((c) => (
+          <Button key={c} {...args} color={c}>
+            {c[0].toUpperCase() + c.slice(1)}
+          </Button>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const Sizes: Story = {
+  args: { color: 'primary', variant: 'contained' },
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap' }}>
+      <Button {...args} size="small">Small</Button>
+      <Button {...args} size="medium">Medium</Button>
+      <Button {...args} size="large">Large</Button>
+    </div>
+  ),
+};
+
+export const WithIcons: Story = {
+  args: {
+    variant: 'contained',
+    color: 'secondary',
+    startIcon: 'mui:Power',
+    endIcon: 'lucide:bolt',
+    children: 'Send',
+  },
+};
+
+export const PolymorphicAnchor: Story = {
+  args: {
+    variant: 'text',
+    color: 'primary',
+    children: 'Go to neurons.me',
+  },
+  render: (args) => (
+    <Button component="a" href="https://neurons.me">
+      {args.children}
+    </Button>
+  ),
+};
+
+export const PolymorphicRouterLink: Story = {
+  args: {
+    variant: 'text',
+    color: 'primary',
+    children: 'Go to /docs',
+  },
+  render: (args) => (
+    <Button component={Link} to="/docs">
+      {args.children}
+    </Button>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { variant: 'contained', color: 'primary', disabled: true, children: 'Disabled' },
+};
+
+export const FullWidth: Story = {
+  args: { variant: 'contained', color: 'primary', fullWidth: true, children: 'Full Width' },
+};

package/src/gui/atoms/Button/Button.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import MuiButton from '@mui/material/Button';
+import type { OverridableComponent } from '@mui/material/OverridableComponent';
+import type { ButtonTypeMap } from '@mui/material/Button';
+import type { ButtonProps as MuiButtonProps } from '@mui/material/Button';
+import Icon from '@/themes/icons/Icon';
+/**
+ * Button (This.GUI primitive)
+ * ----------------------------------------
+ * - Polymorphic: preserves MUI's `component` API and typing via OverridableComponent.
+ * - Enhances MUI by allowing `startIcon` / `endIcon` to be a declarative string
+ *   (e.g., "mui:Settings" / "lucide:camera") or a ReactNode.
+ */
+// Polymorphic props type that matches MUI Button while letting us tweak icon props
+export type Iconish = ReactNode | string | undefined;
+export type ButtonProps = Omit<MuiButtonProps, 'startIcon' | 'endIcon'> & {
+  startIcon?: Iconish;
+  endIcon?: Iconish;
+};
+function resolveIcon(node: Iconish): ReactNode | null {
+  if (!node) return null;
+  return typeof node === 'string' ? <Icon name={node} size={18} /> : node;
+}
+const ButtonImpl = React.forwardRef<any, ButtonProps>(function Button(
+  { startIcon, endIcon, ...rest },
+  ref
+) {
+  return (
+    <MuiButton
+      ref={ref}
+      startIcon={resolveIcon(startIcon)}
+      endIcon={resolveIcon(endIcon)}
+      {...rest}
+    />
+  );
+}) as unknown as OverridableComponent<ButtonTypeMap<{}, 'button'>>;
+(ButtonImpl as any).displayName = 'Button';
+export default ButtonImpl;
+export type GuiButtonProps = React.ComponentProps<typeof ButtonImpl>;

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

@@ -0,0 +1,85 @@
+// src/gui/atoms/Collapse/Collapse.resolver.tsx
+import * as React from 'react';
+import Collapse from './Collapse';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { TransitionProps } from '@mui/material/transitions';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative resolver for Collapse
+ * ---------------------------------
+ * Fidelity
+ * - Forwards MUI props faithfully (in, orientation, collapsedSize, timeout, easing, unmountOnExit, etc.).
+ * - Supports polymorphism via `component` (and alias `as`).
+ * - Provides granular styling through `sx` on the root.
+ *
+ * Usage (declarative JSON):
+ * {
+ *   "type": "Collapse",
+ *   "props": {
+ *     "in": true,
+ *     "orientation": "vertical",
+ *     "sx": { "border": "1px dashed", "borderColor": "divider" }
+ *   }
+ * }
+ */
+export type CollapseSpec = {
+  type: 'Collapse';
+  props?: {
+    children?: React.ReactNode;
+
+    // Note: MUI Collapse's `component` must be a React component (not a string tag) due to Transition typing.
+    component?: React.ElementType<TransitionProps>;
+    as?: any; // alias of component
+
+    // Core MUI props (subset; others passthrough)
+    in?: boolean;
+    orientation?: 'vertical' | 'horizontal';
+    collapsedSize?: number | string;
+    timeout?: 'auto' | number | { appear?: number; enter?: number; exit?: number };
+    easing?: string | { enter?: string; exit?: string };
+    unmountOnExit?: boolean;
+    mountOnEnter?: boolean;
+    appear?: boolean;
+
+    // Styling
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // Arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const CollapseResolver: RegistryEntry = {
+  type: 'Collapse',
+  resolve(spec: CollapseSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const { children, as: _as, component: _component, ...rest } = p;
+    // Collapse's `component` must be a React component (not a string tag), otherwise TS will error.
+    const rawComponent = _component ?? _as;
+    const component = (typeof rawComponent === 'string'
+      ? undefined
+      : (rawComponent as React.ElementType<TransitionProps>)) as React.ElementType<TransitionProps> | undefined;
+
+    // Guarantee a stable, prefixed id for editor tooling
+    const collapseId = ensureNodeId('collapse', p.id);
+    return (
+      <Collapse
+        {...(component ? { component: component as React.ElementType<TransitionProps> } : {})}
+        sx={p.sx}
+        className={p.className}
+        id={collapseId}
+        data-testid={p['data-testid']}
+        {...rest}
+      >
+        {children}
+      </Collapse>
+    );
+  },
+};
+
+export default CollapseResolver;

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

@@ -0,0 +1,136 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import Collapse from './Collapse';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+
+const meta: Meta<typeof Collapse> = {
+  title: 'Atoms/Collapse',
+  component: Collapse,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 220 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Collapse** atom is a thin wrapper around MUI's \`MuiCollapse\`, staying faithful to its API and polymorphism.
+
+In **declarative** mode (resolver), it forwards MUI props as-is and supports granular styling via \`sx\` on the root.
+
+---
+## React usage
+~~~jsx
+const [open, setOpen] = React.useState(true);
+
+<Collapse in={open}>
+  <div style={{ padding: 12, border: '1px solid var(--mui-palette-divider)', borderRadius: 8 }}>
+    Collapsible content
+  </div>
+</Collapse>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "Collapse",
+  "props": {
+    "in": true,
+    "orientation": "vertical",
+    "sx": { "border": "1px dashed", "borderColor": "divider", "p": 1 }
+  }
+}
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'children', 'as', 'timeout', 'easing'],
+    },
+  },
+  argTypes: {
+    in: { control: 'boolean', description: 'Show/Hide content' },
+    orientation: { control: { type: 'radio' }, options: ['vertical', 'horizontal'] },
+    collapsedSize: { control: 'text', description: 'number or CSS size' },
+    unmountOnExit: { control: 'boolean' },
+    mountOnEnter: { control: 'boolean' },
+    appear: { control: 'boolean' },
+    sx: { control: 'object' },
+  },
+  args: {
+    in: true,
+    orientation: 'vertical',
+    collapsedSize: 0,
+    unmountOnExit: false,
+    mountOnEnter: false,
+    appear: false,
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Collapse>;
+
+const DemoBlock: React.FC<{ label?: string } & React.HTMLAttributes<HTMLDivElement>> = ({ label = 'Collapsible content', ...rest }) => (
+  <div
+    {...rest}
+    style={{
+      padding: 12,
+      border: '1px solid var(--mui-palette-divider)',
+      borderRadius: 8,
+      background: 'var(--mui-palette-background-paper)',
+      ...rest.style,
+    }}
+  >
+    {label}
+  </div>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => <Collapse {...args}><DemoBlock /></Collapse>,
+};
+
+export const Horizontal: Story = {
+  args: { orientation: 'horizontal', in: true, collapsedSize: 0 },
+  render: (args) => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+      <Collapse {...args}>
+        <DemoBlock label="Horizontal content" style={{ width: 240 }} />
+      </Collapse>
+      <span style={{ opacity: 0.7, fontSize: 12 }}>(Try toggling the \"in\" control)</span>
+    </div>
+  ),
+};
+
+export const WithSx: Story = {
+  args: { sx: { border: '1px dashed', borderColor: 'divider', p: 1 } },
+  render: (args) => (
+    <Collapse {...args}>
+      <DemoBlock label="Styled via sx on Collapse" />
+    </Collapse>
+  ),
+};
+
+export const UnmountOnExit: Story = {
+  args: { unmountOnExit: true, in: false },
+  render: (args) => (
+    <div>
+      <p style={{ margin: 0, opacity: 0.75 }}>Content is removed from the DOM when closed.</p>
+      <Collapse {...args}>
+        <DemoBlock label="Unmounts when closed" />
+      </Collapse>
+    </div>
+  ),
+};

package/src/gui/atoms/Collapse/Collapse.tsx

@@ -0,0 +1,17 @@
+/**
+ * This.GUI — Collapse
+ * Thin wrapper around MUI’s Collapse that preserves props & typing.
+ *
+ * Fidelity
+ * - Directly re-exports MUI’s component so behavior/typing remain intact.
+ * - No custom logic; consumers keep using it exactly like MUI.
+ *
+ * Styling / Granular control
+ * - Supports MUI System styling via props exposed by MUI (e.g. `sx` on slots where applicable).
+ */
+import * as React from 'react';
+import MuiCollapse from '@mui/material/Collapse';
+const Collapse = MuiCollapse;
+export type CollapseProps = React.ComponentProps<typeof Collapse>;
+(Collapse as any).displayName = 'Gui.Collapse';
+export default Collapse;

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

@@ -0,0 +1,95 @@
+import * as React from 'react';
+import { Divider } from '@/gui/atoms';
+import type { SxProps, Theme } from '@mui/material/styles';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * DividerResolver — declarative adapter for MUI Divider
+ *
+ * Fidelity
+ * - Forwards MUI props faithfully (orientation, flexItem, light, variant, textAlign, etc.).
+ * - Supports polymorphism via `component` (and alias `as`) when compatible with MUI Divider.
+ * - Granular styling via `sx` on the root Divider.
+ *
+ * Sugar
+ * - `text`: convenience for inline content (maps to children). If both `children` and `text`
+ *   are provided, `children` takes precedence.
+ *
+ * JSON example:
+ * {
+ *   "type": "Divider",
+ *   "props": {
+ *     "orientation": "vertical",
+ *     "flexItem": true,
+ *     "text": "OR",
+ *     "sx": { "borderColor": "primary.main" }
+ *   }
+ * }
+ */
+export type DividerSpec = {
+  type: 'Divider';
+  props?: {
+    // Content
+    children?: React.ReactNode;
+    text?: React.ReactNode; // convenience alias for children
+
+    // Polymorphism
+    component?: React.ElementType | string;
+    as?: React.ElementType | string; // alias for component
+
+    // Common MUI Divider props (subset; passthrough handles the rest)
+    orientation?: 'horizontal' | 'vertical';
+    flexItem?: boolean;
+    light?: boolean;
+    variant?: 'fullWidth' | 'inset' | 'middle';
+    textAlign?: 'center' | 'left' | 'right';
+
+    // Styling & misc
+    sx?: SxProps<Theme>;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+
+    // Arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const DividerResolver: RegistryEntry = {
+  type: 'Divider',
+  resolve(spec: DividerSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    // Extract and sanitize resolver-only fields so they don't leak to DOM
+    const {
+      children,
+      text,
+      as: _as,
+      component: _component,
+      sx,
+      className,
+      id,
+      'data-testid': dataTestId,
+      ...rest
+    } = p;
+
+    const component = (_component ?? _as) as React.ElementType | string | undefined;
+    const content = children ?? text ?? undefined;
+    const dividerId = ensureNodeId('divider', id);
+
+    return (
+      <Divider
+        {...(component ? { component } : {})}
+        sx={sx}
+        className={className}
+        id={dividerId}
+        data-testid={dataTestId}
+        {...rest}
+      >
+        {content}
+      </Divider>
+    );
+  },
+};
+
+export default DividerResolver;