this.gui 1.0.17 → 1.1.0

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

@@ -0,0 +1,191 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import Paper from './Paper';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+
+const meta: Meta<typeof Paper> = {
+  title: 'Atoms/Paper',
+  component: Paper,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 240, background: 'var(--mui-palette-background-default)' }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Paper** atom is a thin wrapper around MUI's \`MuiPaper\` that preserves **polymorphism** via the \`component\` prop and passes through all MUI props.
+It integrates with **This.GUI** theming and supports **declarative specs** through the Paper resolver.
+
+---
+## Features
+- Variants: \`elevation\`, \`outlined\`
+- Elevation: \`0..24\`
+- \`square\` boolean
+- **Polymorphic** via \`component\` (e.g., \`'div'\`, \`'section'\`, \`'a'\`)
+- **Routing default** in declarative mode: if \`to\` is provided (and no explicit \`component\`), resolver renders This.GUI \`Link\`
+- Full **system props** passthrough via \`sx\` (and regular MUI system props)
+
+---
+## Basic usage
+~~~jsx
+import Paper from '@/gui/atoms/Paper/Paper';
+
+<Paper elevation={2} sx={{ p: 2, borderRadius: 2 }}>
+  Content
+</Paper>
+~~~
+
+## Polymorphic
+~~~jsx
+<Paper component="section" variant="outlined" sx={{ p: 2 }}>
+  I'm a &lt;section&gt;
+</Paper>
+
+<Paper component="a" href="/docs" sx={{ p: 2, textDecoration: 'none' }}>
+  Go to docs
+</Paper>
+~~~
+
+*Note:* The \`component\` prop is demonstrated via dedicated stories (not Controls) because Storybook's args typing for MUI OverridableComponent can incorrectly narrow props and flag \`component\` as invalid in the Controls panel.
+
+## Declarative JSON / Resolver
+When using the registry-driven renderer, a Paper spec like this:
+
+~~~json
+{
+  "type": "Paper",
+  "props": {
+    "variant": "outlined",
+    "elevation": 0,
+    "component": "section",
+    "sx": { "p": 2, "borderRadius": 2 },
+    "children": "Content"
+  }
+}
+~~~
+
+**Routing (declarative default)** — If you provide \`to\` (and **omit** \`component\`), the resolver will render using This.GUI \`Link\`:
+
+~~~json
+{
+  "type": "Paper",
+  "props": {
+    "to": "/docs",
+    "sx": { "p": 2 },
+    "children": "Go to docs"
+  }
+}
+~~~
+
+The resolver:
+- Chooses \`component\` by priority: explicit \`component\` → \`as\` → (\`to\` ⇒ This.GUI \`Link\`) → (\`external\` ⇒ \`'a'\`)
+- For \`external: true\`, applies safe defaults: \`target="_blank"\`, \`rel="noopener noreferrer"\`
+- Cleans resolver-only keys so they don't leak into the DOM
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component'],
+    },
+  },
+  argTypes: {
+    variant: {
+      control: { type: 'radio' },
+      options: ['elevation', 'outlined'],
+    },
+    elevation: {
+      control: { type: 'range', min: 0, max: 24, step: 1 },
+    },
+    square: {
+      control: 'boolean',
+    },
+    sx: {
+      control: 'object',
+    },
+  },
+  args: {
+    variant: 'elevation',
+    elevation: 1,
+    square: false,
+    children: 'Paper content',
+    sx: { p: 2 },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Paper>;
+
+// ======================= Stories =======================
+export const Playground: Story = {};
+
+export const Variants: Story = {
+  render: (args) => (
+    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
+      <Paper {...args} variant="elevation">Elevation (default)</Paper>
+      <Paper {...args} variant="outlined">Outlined</Paper>
+    </div>
+  ),
+};
+
+export const Elevations: Story = {
+  args: { variant: 'elevation' },
+  render: (args) => {
+    const levels = [0, 1, 2, 3, 4, 6, 8, 12, 16, 24];
+    return (
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(140px, 1fr))', gap: 12 }}>
+        {levels.map((e) => (
+          <Paper key={e} {...args} elevation={e} sx={{ p: 2 }}>
+            elevation={e}
+          </Paper>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const PolymorphicSection: Story = {
+  args: { variant: 'outlined', children: 'I render as <section>' },
+  render: (args) => (
+    <Paper {...args} component="section">
+      {args.children}
+    </Paper>
+  ),
+};
+
+export const PolymorphicAnchor: Story = {
+  args: { children: 'I render as <a href="/docs">', sx: { p: 2, textDecoration: 'none' } },
+  render: (args) => (
+    <Paper component="a" href="/docs" sx={args.sx}>
+      {args.children}
+    </Paper>
+  ),
+};
+
+export const WithSystemProps: Story = {
+  name: 'With system props',
+  args: { variant: 'outlined' },
+  render: (args) => (
+    <Paper {...args} sx={{ p: 2, m: 1, display: 'inline-block', borderRadius: 2 }}>
+      Padding, margin, display via system props.
+    </Paper>
+  ),
+};
+
+export const WithSx: Story = {
+  args: { variant: 'outlined' },
+  render: (args) => (
+    <Paper {...args} sx={{ p: 2, borderRadius: 2, borderStyle: 'dashed' }}>
+      Custom \`sx\` styling (dashed outline).
+    </Paper>
+  ),
+};

package/src/gui/atoms/Paper/Paper.tsx

@@ -0,0 +1,17 @@
+/*
+ * This.GUI — Paper (polymorphic)
+ * Thin wrapper that preserves MUI's own typing and `component` API.
+ * Examples:
+ *   <Paper elevation={3} />
+ *   <Paper component="section" square variant="outlined" />
+ *   <Paper component="a" href="/docs" />
+ */
+import MuiPaper from '@mui/material/Paper';
+import * as React from 'react';
+
+// Re-export using MUI's own component type to keep polymorphism and full typing
+const Paper = MuiPaper;
+export type PaperProps = React.ComponentProps<typeof Paper>;
+
+(Paper as any).displayName = 'Gui.Paper';
+export default Paper;

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

@@ -0,0 +1,94 @@
+// src/gui/atoms/Stack/Stack.resolver.tsx
+import * as React from 'react';
+import Stack from './Stack';
+import Link from '../Link/Link';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+/**
+ * Declarative spec for Stack (layout primitive)
+ *
+ * Notes
+ * - Choose the rendered element via `component` (e.g. 'div', 'section', 'a', custom).
+ * - If `to` is provided (and no explicit component), the resolver will default to This.GUI `Link`.
+ * - If `external` is true (and no explicit component), it will default to an anchor (`'a'`) and apply
+ *   safe `target`/`rel` defaults.
+ * - Common Stack props (direction, spacing, divider, alignItems, justifyContent, useFlexGap, flexWrap, etc.) are passed through.
+ */
+export type StackSpec = {
+  type: 'Stack';
+  props?: {
+    children?: React.ReactNode;
+    // Polymorphism / routing
+    component?: any; // 'div' | 'section' | 'a' | Link | custom
+    as?: any;        // alias for component
+    to?: string;     // router target (when component={Link})
+    href?: string;   // anchor target (when component='a')
+    external?: boolean; // force external anchor
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+    // Core Stack props (subset; rest is passthrough)
+    direction?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
+    spacing?: number | string;
+    divider?: React.ReactNode;
+    useFlexGap?: boolean;
+    alignItems?: React.CSSProperties['alignItems'];
+    justifyContent?: React.CSSProperties['justifyContent'];
+    flexWrap?: React.CSSProperties['flexWrap'];
+    // Styling & misc
+    sx?: any;
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+    // Allow system props / arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const StackResolver: RegistryEntry = {
+  type: 'Stack',
+  resolve(spec: StackSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const nodeId = ensureNodeId('Stack', p.id);
+    // Decide polymorphic target
+    const component = p.component ?? p.as ?? (p.to ? Link : p.external ? 'a' : undefined);
+    // Routing/anchor props
+    const routingProps =
+      component === 'a' || p.external
+        ? {
+            href: p.href,
+            target: p.target ?? (p.external ? '_blank' : undefined),
+            rel: p.rel ?? (p.external ? 'noopener noreferrer' : undefined),
+          }
+        : component === Link || (p.to && !p.component)
+        ? { to: p.to }
+        : {};
+    // Collect common props and avoid leaking resolver-only keys
+    const {
+      children,
+      as: _as,
+      external: _external,
+      to: _to,
+      href: _href,
+      target: _target,
+      rel: _rel,
+      id: _id,
+      'data-testid': _dataTestId,
+      ...rest
+    } = p;
+    return (
+      <Stack
+        component={component}
+        sx={p.sx}
+        id={nodeId}
+        className={p.className}
+        data-testid={p['data-testid']}
+        {...routingProps}
+        {...rest}
+      >
+        {children}
+      </Stack>
+    );
+  },
+};
+
+export default StackResolver;

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

@@ -0,0 +1,166 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import Stack from './Stack';
+import Paper from '../Paper/Paper';
+import Link from '../Link/Link';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+
+const meta: Meta<typeof Stack> = {
+  title: 'Atoms/Stack',
+  component: Stack,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 240 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **Stack** atom is a thin wrapper around MUI's \`MuiStack\` that preserves **polymorphism** and forwards all layout props.
+It integrates with **This.GUI** theming and supports **declarative specs** through the Stack resolver.
+
+---
+## Features
+- Direction: \`row\`, \`column\`, and reverse variants
+- Spacing/gap via \`spacing\`
+- Optional \`divider\`
+- Alignment: \`alignItems\`, \`justifyContent\`, \`flexWrap\`
+- **Polymorphic** via \`component\` (e.g. 'div', 'section', 'a')
+- Full **system props** passthrough via \`sx\`
+
+---
+## Basic usage
+~~~jsx
+<Stack direction="row" spacing={2}>
+  <Item />
+  <Item />
+</Stack>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "Stack",
+  "props": {
+    "direction": "row",
+    "spacing": 2,
+    "sx": { "alignItems": "center" },
+    "children": [
+      { "type": "Paper", "props": { "sx": { "p": 1 }, "children": "A" } },
+      { "type": "Paper", "props": { "sx": { "p": 1 }, "children": "B" } }
+    ]
+  }
+}
+~~~
+
+*Note:* We demonstrate polymorphism in dedicated stories rather than Controls to avoid type-narrowing issues with MUI's OverridableComponent.
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component'],
+    },
+  },
+  argTypes: {
+    direction: {
+      control: { type: 'radio' },
+      options: ['row', 'row-reverse', 'column', 'column-reverse'],
+    },
+    spacing: {
+      control: { type: 'range', min: 0, max: 8, step: 0.5 },
+    },
+    useFlexGap: {
+      control: 'boolean',
+    },
+    sx: {
+      control: 'object',
+    },
+  },
+  args: {
+    direction: 'row',
+    spacing: 1.5,
+    useFlexGap: true,
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Stack>;
+
+const Item = ({ children }: { children: React.ReactNode }) => (
+  <Paper variant="outlined" sx={{ p: 1.5, borderRadius: 1 }}>
+    {children}
+  </Paper>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <Stack {...args}>
+      <Item>A</Item>
+      <Item>B</Item>
+      <Item>C</Item>
+    </Stack>
+  ),
+};
+
+export const RowSpacing: Story = {
+  args: { direction: 'row', spacing: 2 },
+  render: (args) => (
+    <Stack {...args}>
+      <Item>A</Item>
+      <Item>B</Item>
+      <Item>C</Item>
+    </Stack>
+  ),
+};
+
+export const ColumnSpacing: Story = {
+  args: { direction: 'column', spacing: 1.5 },
+  render: (args) => (
+    <Stack {...args} sx={{ width: 240 }}>
+      <Item>A</Item>
+      <Item>B</Item>
+      <Item>C</Item>
+    </Stack>
+  ),
+};
+
+export const WithDivider: Story = {
+  render: (args) => (
+    <Stack {...args} direction="row" spacing={2} divider={<span style={{ opacity: 0.5 }}>|</span>}>
+      <Item>A</Item>
+      <Item>B</Item>
+      <Item>C</Item>
+    </Stack>
+  ),
+};
+
+export const PolymorphicSection: Story = {
+  render: (args) => (
+    <Stack {...args} component="section" spacing={1.5}>
+      <Item>Section A</Item>
+      <Item>Section B</Item>
+    </Stack>
+  ),
+};
+
+export const PolymorphicRouterLink: Story = {
+  render: (args) => (
+    <Link to="/docs" style={{ textDecoration: 'none' }}>
+      <Stack {...args} spacing={1.5}>
+        <Item>Go to Docs</Item>
+      </Stack>
+    </Link>
+  ),
+};

package/src/gui/atoms/Stack/Stack.tsx

@@ -0,0 +1,15 @@
+/*
+ * This.GUI — Stack (polymorphic)
+ * Thin wrapper that preserves MUI's own typing and `component` API.
+ * Examples:
+ *   <Stack direction="row" spacing={2} />
+ *   <Stack component="section" gap={1} />
+ *   <Stack component="a" href="/docs" />
+ */
+import MuiStack from '@mui/material/Stack';
+import * as React from 'react';
+// Re-export using MUI's own component type to keep polymorphism and full typing
+const Stack = MuiStack;
+export type StackProps = React.ComponentProps<typeof Stack>;
+(Stack as any).displayName = 'Gui.Stack';
+export default Stack;

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

@@ -0,0 +1,53 @@
+import * as React from 'react';
+import Switch from './Switch';
+import { FormControlLabel } from '@mui/material';
+import { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Switch.resolver
+ * ------------------------------------------------------------
+ * Allows declarative usage of the Switch atom. You can pass any
+ * MUI Switch prop through, plus optional `label` support. If
+ * `label` is provided, we wrap the control in `FormControlLabel`.
+ *
+ * Examples (JSON-ish):
+ *  {
+ *    type: 'Switch',
+ *    props: { checked: true, color: 'primary', size: 'small' }
+ *  }
+ *
+ *  {
+ *    type: 'Switch',
+ *    props: { label: 'Enable feature', defaultChecked: true }
+ *  }
+ */
+
+export type SwitchResolverProps = React.ComponentProps<typeof Switch> & {
+  /** Optional text/element label to render alongside the switch */
+  label?: React.ReactNode;
+  /** Label position when `label` is provided */
+  labelPlacement?: 'end' | 'start' | 'top' | 'bottom';
+  sx?: SxProps<Theme>;
+  guiId?: string;
+};
+
+export default function resolveSwitch(props: SwitchResolverProps) {
+  const { label, labelPlacement = 'end', guiId, sx, ...rest } = props || ({} as SwitchResolverProps);
+
+  const nodeId = ensureNodeId('Switch', guiId);
+
+  const control = <Switch id={nodeId} sx={sx} {...rest} />;
+
+  if (label != null) {
+    return (
+      <FormControlLabel
+        control={control}
+        label={label}
+        labelPlacement={labelPlacement}
+      />
+    );
+  }
+
+  return control;
+}