this.gui 1.3.24 → 1.3.26

package/src/gui/components/atoms/Link/Link.tsx

@@ -0,0 +1,36 @@
+import React, { forwardRef, Suspense } from 'react';
+import { Link as MuiLink, LinkProps as MuiLinkProps } from '@mui/material';
+import { useInRouterContext } from 'react-router-dom';
+import type { LinkProps as RouterLinkProps } from 'react-router-dom';
+
+type GuiLinkProps = MuiLinkProps & { to?: RouterLinkProps['to'] };
+
+/**
+ * Safe Link wrapper for MUI + React Router
+ */
+const Link = forwardRef<HTMLAnchorElement, GuiLinkProps>(function Link(props, ref) {
+  const { to, ...rest } = props;
+  const inRouterContext = useInRouterContext();
+
+  if (!to) return <MuiLink ref={ref} {...rest} />;
+
+  if (!inRouterContext) {
+    const href = typeof to === 'string' ? to : undefined;
+    return <MuiLink href={href} ref={ref} {...rest} />;
+  }
+
+  // ✅ Lazy load RouterLink only inside router context
+  const RouterLink = React.lazy(async () => {
+    const mod = await import('react-router-dom');
+    return { default: mod.Link };
+  });
+
+  return (
+    <Suspense fallback={<MuiLink ref={ref} {...rest} />}>
+      <MuiLink component={RouterLink} to={to} ref={ref} {...rest} />
+    </Suspense>
+  );
+});
+
+export default Link;
+export type { GuiLinkProps as LinkProps };

package/src/gui/components/atoms/List/List.resolver.tsx

@@ -0,0 +1,94 @@
+// src/gui/atoms/List/List.resolver.tsx
+import * as React from 'react';
+import List from './List';
+import ListSubheader from '@mui/material/ListSubheader';
+import type { RegistryEntry, ResolveCtx } from '@/registry/types';
+import type { SxProps, Theme } from '@mui/material/styles';
+import { ensureNodeId } from '@/gui/utils/nodeID';
+/**
+ * Declarative resolver for List
+ *
+ * Fidelity
+ * - Forwards MUI props faithfully (dense, disablePadding, subheader, etc.).
+ * - Supports polymorphism via `component` (and alias `as`).
+ * - Provides **granular styling** via `sx` (root) and optional `subheaderSx`.
+ * - Generates a stable id via `ensureNodeId`.
+ *
+ * Sugar
+ * - `subheaderText`: if provided (and `subheader` not provided), we render
+ *   a `<ListSubheader />` with that text. You can style it via `subheaderSx`.
+ *
+ * Note: Routing props (`href`, `to`, `external`) are not handled at the List level.
+ */
+export type ListSpec = {
+  type: 'List';
+  props?: {
+    children?: React.ReactNode;
+    // Polymorphism
+    component?: any;
+    as?: any; // alias of component
+    // MUI props (subset; others passthrough)
+    dense?: boolean;
+    disablePadding?: boolean;
+    subheader?: React.ReactNode;
+    // Sugar
+    subheaderText?: React.ReactNode;
+    subheaderSx?: SxProps<Theme>;
+    // Styling
+    sx?: SxProps<Theme>; // root styles
+    className?: string;
+    id?: string;
+    'data-testid'?: string;
+    // Arbitrary passthrough
+    [key: string]: any;
+  };
+};
+
+const ListResolver: RegistryEntry = {
+  type: 'List',
+  resolve(spec: ListSpec, _ctx?: ResolveCtx) {
+    const p = spec.props ?? {};
+    const id = ensureNodeId('list', p.id);
+    const component = p.component ?? p.as;
+    const {
+      children,
+      subheader,
+      subheaderText,
+      subheaderSx,
+      // strip resolver-only alias
+      as: _as,
+      // passthrough rest (dense, disablePadding, sx, etc.)
+      ...rest
+    } = p;
+    const effectiveSubheader =
+      subheader != null
+        ? subheader
+        : subheaderText != null
+        ? (
+            <ListSubheader component="div" sx={subheaderSx}>
+              {subheaderText}
+            </ListSubheader>
+          )
+        : undefined;
+
+    const rootProps: any = {
+      ...rest,
+      sx: p.sx,
+      className: p.className,
+      id,
+      'data-testid': p['data-testid'],
+      subheader: effectiveSubheader,
+    };
+    if (component !== undefined) {
+      rootProps.component = component;
+    }
+
+    return (
+      <List {...rootProps}>
+        {children}
+      </List>
+    );
+  },
+};
+
+export default ListResolver;

package/src/gui/components/atoms/List/List.stories.tsx

@@ -0,0 +1,137 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import List from './List';
+import ListItem from '../ListItem/ListItem';
+import ListItemIcon from '@/gui/components/atoms/ListItemIcon/ListItemIcon';
+import ListItemText from '@/gui/components/atoms/ListItemText/ListItemText';
+import Icon from '@/gui/Theme/Icon/Icon';
+import ListSubheader from '@mui/material/ListSubheader';
+
+const meta: Meta<typeof List> = {
+  title: 'Atoms/Organization/List',
+  component: List,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+        <div style={{ padding: 16, minHeight: 260, maxWidth: 560 }}>
+          <Story />
+        </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The **List** atom is a thin wrapper around MUI's \`MuiList\`, staying faithful to its API and polymorphism.
+
+In **declarative** mode (resolver), it forwards MUI props and supports granular styling via \`sx\`.
+It also provides sugar: \`subheaderText\` (and \`subheaderSx\`) to easily render a \`<ListSubheader/>\` when you don't pass \`subheader\` explicitly.
+
+---
+## React usage
+~~~jsx
+<List dense subheader={<li />}> // arbitrary subheader (from MUI API)
+  <ListItem>
+    <ListItemIcon>
+      <Icon name="lucide:inbox" />
+    </ListItemIcon>
+    <ListItemText primary="Inbox" />
+  </ListItem>
+</List>
+~~~
+
+## Declarative JSON / Resolver
+~~~json
+{
+  "type": "List",
+  "props": {
+    "dense": true,
+    "disablePadding": false,
+    "subheaderText": "Shortcuts",
+    "subheaderSx": { "fontWeight": 600 },
+    "sx": { "bgcolor": "background.paper", "borderRadius": 8 }
+  }
+}
+~~~
+*Note:* \`subheaderText\`/\`subheaderSx\` are **resolver-only** sugar; they are not MUI props.
+        `,
+      },
+    },
+    controls: {
+      exclude: ['component', 'children', 'subheader'],
+    },
+  },
+  argTypes: {
+    dense: { control: 'boolean' },
+    disablePadding: { control: 'boolean' },
+    sx: { control: 'object', table: { category: 'Style' } },
+  },
+  args: {
+    dense: false,
+    disablePadding: false,
+    sx: { bgcolor: 'background.paper', borderRadius: 1, border: '1px solid', borderColor: 'divider' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof List>;
+
+const SampleRows: React.FC = () => (
+  <>
+    <ListItem>
+      <ListItemIcon>
+        <Icon name="lucide:inbox" />
+      </ListItemIcon>
+      <ListItemText primary="Inbox" />
+    </ListItem>
+    <ListItem>
+      <ListItemIcon>
+        <Icon name="lucide:send" />
+      </ListItemIcon>
+      <ListItemText primary="Sent" />
+    </ListItem>
+    <ListItem>
+      <ListItemIcon>
+        <Icon name="lucide:star" />
+      </ListItemIcon>
+      <ListItemText primary="Starred" />
+    </ListItem>
+  </>
+);
+
+// ======================= Stories =======================
+export const Playground: Story = {
+  render: (args) => (
+    <List {...args}>
+      <SampleRows />
+    </List>
+  ),
+};
+
+export const WithSubheader: Story = {
+  name: 'With subheader (MUI prop)',
+  render: () => (
+    <List subheader={<ListSubheader component="div" sx={{ fontWeight: 600 }}>Shortcuts</ListSubheader>}>
+      <SampleRows />
+    </List>
+  ),
+};
+
+export const DenseAndNoPadding: Story = {
+  args: { dense: true, disablePadding: true },
+  render: (args) => (
+    <List {...args}>
+      <SampleRows />
+    </List>
+  ),
+};
+
+export const StyledWithSx: Story = {
+  args: { sx: { bgcolor: 'background.paper', borderRadius: 2, boxShadow: 1 } },
+  render: (args) => (
+    <List {...args}>
+      <SampleRows />
+    </List>
+  ),
+};

package/src/gui/components/atoms/List/List.tsx

@@ -0,0 +1,20 @@
+/**
+ * This.GUI — List
+ * Thin wrapper around MUI’s List that preserves MUI props & typing.
+ *
+ * Fidelity
+ * - We directly re-export MUI’s component so all behavior/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).
+ * - Provides a clean surface for a resolver (declarative mode) without
+ *   altering React usage.
+ */
+import * as React from 'react';
+import MuiList from '@mui/material/List';
+const List = MuiList;
+export type ListProps = React.ComponentProps<typeof List>;
+// Helpful display name in React DevTools
+(List as any).displayName = 'Gui.List';
+export default List;

package/src/gui/components/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/components/atoms/ListItem/ListItem.stories.tsx

@@ -0,0 +1,151 @@
+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 '@/gui/components/atoms/ListItemIcon/ListItemIcon';
+import ListItemText from '@/gui/components/atoms/ListItemText/ListItemText';
+import Icon from '@/gui/Theme/Icon/Icon';
+const meta: Meta<typeof ListItem> = {
+  title: 'Atoms/Organization/ListItem',
+  component: ListItem,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div style={{ padding: 16, minHeight: 260, maxWidth: 560 }}>
+        <Story />
+      </div>
+    ),
+  ],
+  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/components/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;