this.gui 1.0.18 → 1.1.0

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

@@ -0,0 +1,88 @@
+// src/gui/atoms/ListItem/ListItem.resolver.tsx
+import * as React from 'react';
+import ListItem from './ListItem';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative resolver for ListItem
+ *
+ * Fidelity
+ * - Forwards all MUI ListItem props faithfully (alignItems, dense, divider, selected, etc.).
+ * - Supports polymorphism via `component` prop (and alias `as`).
+ * - Provides **granular styling** via `sx`.
+ *
+ * Notes
+ * - In declarative (JSON/registry) mode, just pass props as object.
+ * - If children are provided, they render directly.
+ * - We emit a stable editor id under `data-gui-id` (not `id`) to avoid clashing with user-provided DOM ids.
+ */
+export type ListItemSpec = {
+  type: 'ListItem';
+  props?: {
+    children?: React.ReactNode;
+
+    // Polymorphism
+    component?: any;
+    as?: any;
+
+    // MUI props (subset; others passthrough in `...rest`)
+    dense?: boolean;
+    divider?: boolean;
+    disableGutters?: boolean;
+    selected?: boolean;
+    alignItems?: 'flex-start' | 'center';
+    secondaryAction?: React.ReactNode;
+
+    // Styling
+    sx?: SxProps<Theme>;
+    className?: string;
+
+    // Identity & testing
+    id?: string;
+    'data-testid'?: string;
+    'data-gui-id'?: string;
+
+    // Arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const ListItemResolver: RegistryEntry = {
+  type: 'ListItem',
+  resolve(spec: ListItemSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+
+    // Polymorphic target (avoid passing undefined)
+    const component = p.component ?? p.as;
+    const rootPolymorphic = component ? { component } : {};
+
+    // Stable editor id that doesn't clash with user DOM ids
+    const guiId = ensureNodeId('list-item', p['data-gui-id']);
+
+    // Collect props, strip resolver-only keys
+    const {
+      children,
+      as: _as,
+      'data-gui-id': _guiIdIn,
+      ...rest
+    } = p;
+
+    return (
+      <ListItem
+        {...rootPolymorphic}
+        sx={p.sx}
+        className={p.className}
+        id={p.id}
+        data-testid={p['data-testid']}
+        data-gui-id={guiId}
+        {...rest}
+      >
+        {children}
+      </ListItem>
+    );
+  },
+};
+
+export default ListItemResolver;

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

@@ -0,0 +1,157 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import ListItem from './ListItem';
+import List from '@mui/material/List';
+import ListItemIcon from '../ListItemIcon/ListItemIcon';
+import ListItemText from '../ListItemText/ListItemText';
+import Icon from '@/themes/icons/Icon';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+const meta: Meta<typeof ListItem> = {
+  title: 'Atoms/ListItem',
+  component: ListItem,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 260, maxWidth: 560 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **ListItem** atom is a thin wrapper around MUI's \`MuiListItem\`, staying faithful to its API and polymorphism.
+In **declarative** mode (resolver), it simply forwards MUI props and allows granular styling via \`sx\`.
+
+---
+
+## React usage
+~~~jsx
+<List dense>
+  <ListItem divider>
+    <ListItemIcon>
+      <Icon name="lucide:inbox" />
+    </ListItemIcon>
+    <ListItemText primary="Inbox" secondary="Messages" />
+  </ListItem>
+</List>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "ListItem",
+  "props": {
+    "dense": true,
+    "divider": true,
+    "selected": true,
+    "sx": { "py": 1 }
+  }
+}
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'children'],
+    },
+  },
+  argTypes: {
+    dense: { control: 'boolean' },
+    divider: { control: 'boolean' },
+    disableGutters: { control: 'boolean' },
+    alignItems: { control: { type: 'radio' }, options: ['center', 'flex-start'] },
+    sx: { control: 'object' },
+  },
+  args: {
+    dense: false,
+    divider: false,
+    disableGutters: false,
+    alignItems: 'center',
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ListItem>;
+
+const DemoList: React.FC<{ children?: React.ReactNode }> = ({ children }) => (
+  <List dense sx={{ bgcolor: 'background.paper', borderRadius: 1, overflow: 'hidden', border: '1px solid', borderColor: 'divider' }}>
+    {children}
+  </List>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <DemoList>
+      <ListItem {...args}>
+        <ListItemIcon>
+          <Icon name="lucide:inbox" />
+        </ListItemIcon>
+        <ListItemText primary="Inbox" secondary="Messages" />
+      </ListItem>
+    </DemoList>
+  ),
+};
+
+export const Variants: Story = {
+  render: () => (
+    <DemoList>
+      <ListItem>
+        <ListItemIcon>
+          <Icon name="lucide:mail" />
+        </ListItemIcon>
+        <ListItemText primary="Default" secondary="No props" />
+      </ListItem>
+      <ListItem dense>
+        <ListItemIcon>
+          <Icon name="lucide:mail" />
+        </ListItemIcon>
+        <ListItemText primary="Dense" />
+      </ListItem>
+      <ListItem divider>
+        <ListItemIcon>
+          <Icon name="lucide:mail" />
+        </ListItemIcon>
+        <ListItemText primary="With divider" />
+      </ListItem>
+      <ListItem>
+        <ListItemIcon>
+          <Icon name="lucide:mail" />
+        </ListItemIcon>
+        <ListItemText primary="Default (no selected on ListItem)" />
+      </ListItem>
+      <ListItem alignItems="flex-start">
+        <ListItemIcon>
+          <Icon name="lucide:mail" />
+        </ListItemIcon>
+        <ListItemText primary="Align start" secondary="Secondary text that wraps onto multiple lines for demo." />
+      </ListItem>
+    </DemoList>
+  ),
+};
+
+export const WithSx: Story = {
+  render: () => (
+    <DemoList>
+      <ListItem sx={{ py: 1.25, '&:hover': { bgcolor: 'action.hover' } }}>
+        <ListItemIcon sx={{ minWidth: 40 }}>
+          <Icon name="lucide:user" />
+        </ListItemIcon>
+        <ListItemText
+          primary="Profile"
+          secondary="Account"
+          secondaryTypographyProps={{ color: 'text.secondary' }}
+        />
+      </ListItem>
+    </DemoList>
+  ),
+};

package/src/gui/atoms/ListItem/ListItem.tsx

@@ -0,0 +1,19 @@
+/**
+ * This.GUI — ListItem
+ * Thin wrapper around MUI’s ListItem that preserves MUI’s props and typing.
+ *
+ * Fidelity
+ * - We directly re-export MUI’s component so all behavior and typing remain intact.
+ * - Granular styling is supported via the standard `sx` prop (MUI System).
+ *
+ * Why wrap it?
+ * - Consistency with This.GUI’s atom pattern (each atom in its own module).
+ * - Enables a clean spot for a resolver (declarative mode) without changing React usage.
+ */
+import * as React from 'react';
+import MuiListItem from '@mui/material/ListItem';
+const ListItem = MuiListItem;
+export type ListItemProps = React.ComponentProps<typeof ListItem>;
+// Useful name in React DevTools
+(ListItem as any).displayName = 'Gui.ListItem';
+export default ListItem;

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

@@ -0,0 +1,208 @@
+// src/gui/atoms/ListItemButton/ListItemButton.resolver.tsx
+import * as React from 'react';
+import ListItemButton from './ListItemButton';
+import Link from '../Link/Link';
+import Icon from '@/themes/icons/Icon';
+// Use our own thin wrappers for consistency & display names
+import ListItemIcon from '../ListItemIcon/ListItemIcon';
+import ListItemText from '../ListItemText/ListItemText';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import Box from '../Box/Box';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+
+/**
+ * Declarative spec for ListItemButton
+ *
+ * Goals
+ * - Be faithful to MUI's API: forward native props like `selected`, `disabled`, `dense`, `alignItems`, etc.
+ * - Preserve polymorphism via MUI's `component` prop (and alias `as`).
+ * - Add **declarative sugar** (optional):
+ *    - `startIcon` / `endIcon`: string token (e.g., "lucide:mail", "mui:settings") or ReactNode
+ *    - `label` / `secondary`: mapped to `<ListItemText primary/secondary />`
+ * - Add **granular styling** for slots:
+ *    - `sx`         → root ListItemButton
+ *    - `iconSx`     → ListItemIcon (leading)
+ *    - `textSx`     → ListItemText
+ *    - `endIconSx`  → trailing icon container
+ *
+ * Notes
+ * - If `children` are provided, they take precedence and render as-is (no sugar applied).
+ * - Tokens are normalized (lowercased & trimmed) to avoid missing icons due to casing.
+ * - Routing:
+ *    - 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 add safe `target`/`rel`.
+ */
+export type ListItemButtonSpec = {
+  type: 'ListItemButton';
+  props?: {
+    children?: React.ReactNode;
+
+    // Polymorphism / routing
+    component?: any; // 'div' | '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;
+
+    // Sugar (optional)
+    startIcon?: React.ReactNode | string;
+    endIcon?: React.ReactNode | string;
+    iconColor?: string;       // applies to startIcon/endIcon when tokens
+    endIconColor?: string;    // override for trailing icon
+    size?: number;            // icon size (default 20)
+    label?: React.ReactNode | string;
+    secondary?: React.ReactNode | string;
+
+    // MUI props (subset; others passthrough)
+    selected?: boolean;
+    disabled?: boolean;
+    dense?: boolean;
+    alignItems?: 'flex-start' | 'center';
+    divider?: boolean;
+
+    // Granular styling
+    sx?: SxProps<Theme>;          // root
+    iconSx?: SxProps<Theme>;      // leading ListItemIcon
+    textSx?: SxProps<Theme>;      // ListItemText
+    endIconSx?: SxProps<Theme>;   // trailing icon container
+
+    // Slot props passthrough (their own sx can be merged)
+    ListItemIconProps?: { sx?: SxProps<Theme>; [k: string]: any };
+    ListItemTextProps?: { sx?: SxProps<Theme>; [k: string]: any };
+
+    // Editor / telemetry
+    'data-gui-id'?: string;
+
+    // Misc DOM
+    id?: string;
+    className?: string;
+    'data-testid'?: string;
+
+    // Arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const normalizeToken = (s: string) => s.trim().toLowerCase();
+
+function renderIcon(node: React.ReactNode | string | undefined, color?: string, size = 20) {
+  if (!node) return null;
+  return typeof node === 'string'
+    ? <Icon name={normalizeToken(node)} iconColor={color} size={size} />
+    : node;
+}
+
+const ListItemButtonResolver: RegistryEntry = {
+  type: 'ListItemButton',
+  resolve(spec: ListItemButtonSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+
+    // Generate/ensure a stable gui id (does not override an explicit one)
+    const dataGuiId = ensureNodeId('list-item-button', (p as any)['data-gui-id']);
+
+    // Decide polymorphic target (only pass when defined)
+    const decidedComponent = p.component ?? p.as ?? (p.to ? Link : p.external ? 'a' : undefined);
+    const componentProp = decidedComponent ? { component: decidedComponent } : undefined;
+
+    // Routing/anchor props
+    const routingProps =
+      decidedComponent === 'a' || p.external
+        ? {
+            href: p.href,
+            target: p.target ?? (p.external ? '_blank' : undefined),
+            rel: p.rel ?? (p.external ? 'noopener noreferrer' : undefined),
+          }
+        : decidedComponent === Link || (p.to && !p.component)
+        ? { to: p.to }
+        : {};
+
+    // Destructure and clean resolver-only fields
+    const {
+      children,
+      startIcon,
+      endIcon,
+      iconColor,
+      endIconColor,
+      size = 20,
+      ListItemIconProps,
+      ListItemTextProps,
+      iconSx,
+      textSx,
+      endIconSx,
+
+      // strip resolver-only aliasing keys so they don't leak to DOM
+      as: _as,
+      external: _external,
+      to: _to,
+      href: _href,
+      target: _target,
+      rel: _rel,
+
+      // keep rest: native MUI props (selected, dense, disabled, divider, alignItems, sx, etc.)
+      ...rest
+    } = p as any;
+
+    // If explicit children, render as-is (no sugar)
+    if (children != null) {
+      return (
+        <ListItemButton
+          {...componentProp}
+          sx={p.sx}
+          id={p.id}
+          className={p.className}
+          data-testid={p['data-testid']}
+          data-gui-id={dataGuiId}
+          {...routingProps}
+          {...rest}
+        >
+          {children}
+        </ListItemButton>
+      );
+    }
+
+    // Build sugar content
+    const leadingIcon = renderIcon(startIcon, iconColor, size);
+    const trailingIcon = renderIcon(endIcon, endIconColor ?? iconColor, size);
+    const hasText = p.label != null || p.secondary != null;
+
+    // Merge sx for slot props safely (array merge preserves both)
+    const mergedIconSx =
+      iconSx != null && ListItemIconProps?.sx != null ? [iconSx, ListItemIconProps.sx] : iconSx ?? ListItemIconProps?.sx;
+    const mergedTextSx =
+      textSx != null && ListItemTextProps?.sx != null ? [textSx, ListItemTextProps.sx] : textSx ?? ListItemTextProps?.sx;
+
+    const finalIconProps = leadingIcon
+      ? (ListItemIconProps ? { ...ListItemIconProps, sx: mergedIconSx } : (mergedIconSx != null ? { sx: mergedIconSx } : undefined))
+      : undefined;
+
+    const finalTextProps = hasText
+      ? (ListItemTextProps ? { ...ListItemTextProps, sx: mergedTextSx } : (mergedTextSx != null ? { sx: mergedTextSx } : undefined))
+      : undefined;
+
+    return (
+      <ListItemButton
+        {...componentProp}
+        sx={p.sx}
+        id={p.id}
+        className={p.className}
+        data-testid={p['data-testid']}
+        data-gui-id={dataGuiId}
+        {...routingProps}
+        {...rest}
+      >
+        {leadingIcon ? <ListItemIcon {...finalIconProps}>{leadingIcon}</ListItemIcon> : null}
+        {hasText ? <ListItemText primary={p.label} secondary={p.secondary} {...finalTextProps} /> : null}
+        {trailingIcon ? (
+          <Box sx={[{ marginLeft: 'auto', display: 'inline-flex', alignItems: 'center' }, endIconSx as any]}>
+            {trailingIcon}
+          </Box>
+        ) : null}
+      </ListItemButton>
+    );
+  },
+};
+
+export default ListItemButtonResolver;

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

@@ -0,0 +1,161 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import ListItemButton from './ListItemButton';
+import ListItemIcon from '../ListItemIcon/ListItemIcon';
+import ListItemText from '../ListItemText/ListItemText';
+import Icon from '@/themes/icons/Icon';
+import List from '@mui/material/List';
+import ListItem from '@mui/material/ListItem';
+import { MemoryRouter } from 'react-router-dom';
+import GuiProvider from '@/context/GuiProvider';
+
+const meta: Meta<typeof ListItemButton> = {
+  title: 'Atoms/ListItemButton',
+  component: ListItemButton,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <MemoryRouter>
+        <GuiProvider>
+          <div style={{ padding: 16, minHeight: 260, maxWidth: 560 }}>
+            <Story />
+          </div>
+        </GuiProvider>
+      </MemoryRouter>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **ListItemButton** atom is a thin wrapper around MUI's \`MuiListItemButton\`, staying faithful to its API and polymorphism.
+
+In **declarative** mode, the resolver adds sugar:
+- \`startIcon\` / \`endIcon\`: token (e.g., \`"lucide:mail"\`, \`"mui:settings"\`) or ReactNode — rendered via the icon registry
+- \`label\` / \`secondary\` → mapped to \`<ListItemText primary/secondary />\`
+- Granular styling:
+  - \`sx\` (root), \`iconSx\` (leading \`ListItemIcon\`), \`textSx\` (text), \`endIconSx\` (trailing icon container)
+
+---
+## React usage
+~~~jsx
+<List>
+  <ListItem disablePadding>
+    <ListItemButton selected>
+      <ListItemIcon>
+        <Icon name="lucide:mail" />
+      </ListItemIcon>
+      <ListItemText primary="Inbox" secondary="Messages" />
+    </ListItemButton>
+  </ListItem>
+</List>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "ListItemButton",
+  "props": {
+    "startIcon": "lucide:mail",
+    "label": "Inbox",
+    "secondary": "Messages",
+    "sx": { "py": 1 },
+    "iconSx": { "minWidth": 36 },
+    "textSx": { "my": 0 }
+  }
+}
+~~~
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'children'],
+    },
+  },
+  argTypes: {
+    selected: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    dense: { control: 'boolean' },
+    divider: { control: 'boolean' },
+    alignItems: { control: { type: 'radio' }, options: ['center', 'flex-start'] },
+    sx: { control: 'object' },
+  },
+  args: {
+    selected: false,
+    disabled: false,
+    dense: false,
+    divider: false,
+    alignItems: 'center',
+    sx: {},
+    children: undefined,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ListItemButton>;
+
+const DemoList: React.FC<{ children?: React.ReactNode }> = ({ children }) => (
+  <List dense sx={{ bgcolor: 'background.paper', borderRadius: 1, overflow: 'hidden', border: '1px solid', borderColor: 'divider' }}>
+    <ListItem disablePadding>{children}</ListItem>
+  </List>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <DemoList>
+      <ListItemButton {...args}>
+        <ListItemIcon>
+          <Icon name="lucide:mail" />
+        </ListItemIcon>
+        <ListItemText primary="Inbox" secondary="Messages" />
+      </ListItemButton>
+    </DemoList>
+  ),
+};
+
+export const WithTrailingIcon: Story = {
+  render: () => (
+    <DemoList>
+      <ListItemButton>
+        <ListItemIcon>
+          <Icon name="mui:settings" />
+        </ListItemIcon>
+        <ListItemText primary="Settings" secondary="Preferences" />
+        <span style={{ marginLeft: 'auto', display: 'inline-flex' }}>
+          <Icon name="lucide:chevron-right" />
+        </span>
+      </ListItemButton>
+    </DemoList>
+  ),
+};
+
+export const AsAnchorLink: Story = {
+  render: () => (
+    <DemoList>
+      <ListItemButton component="a" href="https://neurons.me">
+        <ListItemIcon>
+          <Icon name="lucide:link" />
+        </ListItemIcon>
+        <ListItemText primary="neurons.me" secondary="External link" />
+      </ListItemButton>
+    </DemoList>
+  ),
+};
+
+export const WithSx: Story = {
+  render: () => (
+    <DemoList>
+      <ListItemButton sx={{ py: 1.25 }}>
+        <ListItemIcon sx={{ minWidth: 40 }}>
+          <Icon name="lucide:user" />
+        </ListItemIcon>
+        <ListItemText
+          primary="Profile"
+          secondary="Account"
+          secondaryTypographyProps={{ color: 'text.secondary' }}
+        />
+      </ListItemButton>
+    </DemoList>
+  ),
+};

package/src/gui/atoms/ListItemButton/ListItemButton.tsx

@@ -0,0 +1,15 @@
+/**
+ * This component is a thin wrapper around MUI’s ListItemButton.
+ * It preserves MUI’s props and typing, staying faithful to MUI.
+ * 
+ * Why wrap it?
+ * - Consistency with This.GUI’s atom pattern (each atom has its own file).
+ * - Supports declarative/resolver usage while keeping all MUI props intact.
+ * - Allows granular style control via `sx`.
+ */
+import * as React from 'react';
+import MuiListItemButton from '@mui/material/ListItemButton';
+const ListItemButton = MuiListItemButton;
+export type ListItemButtonProps = React.ComponentProps<typeof ListItemButton>;
+(ListItemButton as any).displayName = 'Gui.ListItemButton';
+export default ListItemButton;