this.gui 1.0.18 → 1.1.0

package/src/stories/Theme/BreakPointsAndGrids.stories.jsx

@@ -0,0 +1,185 @@
+// src/stories/Theme/BreakPointsAndGrids.stories.jsx
+// Storybook: Theme / Breakpoints & Grid
+// Pure JSX (no MDX blocks). Demonstrates:
+// 1) Reading theme breakpoints
+// 2) Live media-query indicators
+// 3) Responsive Grid examples (xs/sm/md/lg/xl)
+import {
+  Box,
+  Typography,
+  Grid,
+  Paper,
+  Stack,
+  Divider,
+} from '@mui/material';
+import { useTheme } from '@mui/material/styles';
+import useMediaQuery from '@mui/material/useMediaQuery';
+
+export default {
+  title: 'Theme/Breakpoints & Grid',
+};
+
+function BreakpointPill({ label, active }) {
+  return (
+    <Box
+      sx={{
+        px: 1.25,
+        py: 0.5,
+        borderRadius: 999,
+        fontSize: 12,
+        fontWeight: 600,
+        border: '1px solid',
+        borderColor: (t) => (active ? t.palette.primary.main : t.palette.divider),
+        color: (t) => (active ? t.palette.primary.main : t.palette.text.secondary),
+        backgroundColor: (t) => (active ? t.palette.action.hover : 'transparent'),
+        transition: 'all 120ms ease-out',
+        minWidth: 52,
+        textAlign: 'center',
+      }}
+    >
+      {label}
+    </Box>
+  );
+}
+
+function BreakpointsHeader() {
+  const theme = useTheme();
+  const { xs, sm, md, lg, xl } = theme.breakpoints.values;
+
+  const mq = {
+    xs: useMediaQuery(theme.breakpoints.only('xs')),
+    sm: useMediaQuery(theme.breakpoints.only('sm')),
+    md: useMediaQuery(theme.breakpoints.only('md')),
+    lg: useMediaQuery(theme.breakpoints.only('lg')),
+    xl: useMediaQuery(theme.breakpoints.only('xl')),
+    upSm: useMediaQuery(theme.breakpoints.up('sm')),
+    upMd: useMediaQuery(theme.breakpoints.up('md')),
+    upLg: useMediaQuery(theme.breakpoints.up('lg')),
+  };
+
+  return (
+    <Paper variant="outlined" sx={{ p: 2, mb: 3 }}>
+      <Stack direction="row" alignItems="center" justifyContent="space-between" flexWrap="wrap" gap={1.5}>
+        <Typography variant="h5">Breakpoints</Typography>
+        <Stack direction="row" spacing={1}>
+          <BreakpointPill label={`xs ≥ ${xs}px`} active={mq.xs} />
+          <BreakpointPill label={`sm ≥ ${sm}px`} active={mq.sm} />
+          <BreakpointPill label={`md ≥ ${md}px`} active={mq.md} />
+          <BreakpointPill label={`lg ≥ ${lg}px`} active={mq.lg} />
+          <BreakpointPill label={`xl ≥ ${xl}px`} active={mq.xl} />
+        </Stack>
+      </Stack>
+
+      <Divider sx={{ my: 2 }} />
+
+      <Typography variant="body2" sx={{ mb: 1, color: 'text.secondary' }}>
+        Up queries (live):
+      </Typography>
+      <Stack direction="row" spacing={1}>
+        <BreakpointPill label="≥ sm" active={mq.upSm} />
+        <BreakpointPill label="≥ md" active={mq.upMd} />
+        <BreakpointPill label="≥ lg" active={mq.upLg} />
+      </Stack>
+    </Paper>
+  );
+}
+
+function ValuesTable() {
+  const theme = useTheme();
+  const { xs, sm, md, lg, xl } = theme.breakpoints.values;
+
+  const Row = ({ name, px }) => (
+    <Box sx={{ display: 'grid', gridTemplateColumns: '160px 1fr', py: 0.75, borderTop: '1px solid', borderColor: 'divider' }}>
+      <Box sx={{ fontWeight: 600 }}>{name}</Box>
+      <Box sx={{ color: 'text.secondary' }}>{px}px</Box>
+    </Box>
+  );
+
+  return (
+    <Paper variant="outlined" sx={{ p: 2 }}>
+      <Typography variant="h6" sx={{ mb: 1 }}>Breakpoint values</Typography>
+      <Box sx={{ borderBottom: '1px solid', borderColor: 'divider' }} />
+      <Row name="xs" px={xs} />
+      <Row name="sm" px={sm} />
+      <Row name="md" px={md} />
+      <Row name="lg" px={lg} />
+      <Row name="xl" px={xl} />
+    </Paper>
+  );
+}
+
+function Block({ children }) {
+  return (
+    <Paper
+      elevation={0}
+      variant="outlined"
+      sx={{
+        p: 2,
+        textAlign: 'center',
+        borderStyle: 'dashed',
+        bgcolor: 'background.paper',
+      }}
+    >
+      <Typography variant="body2" sx={{ color: 'text.secondary' }}>{children}</Typography>
+    </Paper>
+  );
+}
+
+function ResponsiveGridDemo() {
+  return (
+    <Paper variant="outlined" sx={{ p: 2 }}>
+      <Typography variant="h6" sx={{ mb: 2 }}>Responsive Grid</Typography>
+      <Typography variant="body2" sx={{ mb: 2, color: 'text.secondary' }}>
+        This grid uses props like <code>xs</code>, <code>sm</code>, <code>md</code>, etc. Resize the canvas to see items reflow.
+      </Typography>
+
+      <Grid container spacing={2}>
+        <Grid item xs={12} sm={6} md={4} lg={3} xl={2}><Block>xs=12 sm=6 md=4 lg=3 xl=2</Block></Grid>
+        <Grid item xs={12} sm={6} md={4} lg={3} xl={2}><Block>xs=12 sm=6 md=4 lg=3 xl=2</Block></Grid>
+        <Grid item xs={12} sm={6} md={4} lg={3} xl={2}><Block>xs=12 sm=6 md=4 lg=3 xl=2</Block></Grid>
+        <Grid item xs={12} sm={6} md={4} lg={3} xl={2}><Block>xs=12 sm=6 md=4 lg=3 xl=2</Block></Grid>
+        <Grid item xs={12} sm={6} md={4} lg={3} xl={2}><Block>xs=12 sm=6 md=4 lg=3 xl=2</Block></Grid>
+        <Grid item xs={12} sm={6} md={4} lg={3} xl={2}><Block>xs=12 sm=6 md=4 lg=3 xl=2</Block></Grid>
+      </Grid>
+
+      <Divider sx={{ my: 3 }} />
+
+      <Typography variant="h6" sx={{ mb: 2 }}>Auto layout</Typography>
+      <Typography variant="body2" sx={{ mb: 2, color: 'text.secondary' }}>
+        Below, items auto-size to content on each breakpoint.
+      </Typography>
+
+      <Grid container spacing={2}>
+        <Grid item xs>
+          <Block>xs (auto)</Block>
+        </Grid>
+        <Grid item xs={6} md={3}>
+          <Block>xs=6 md=3</Block>
+        </Grid>
+        <Grid item xs>
+          <Block>xs (auto)</Block>
+        </Grid>
+      </Grid>
+    </Paper>
+  );
+}
+
+export const Overview = () => (
+  <Box sx={{ p: 2, display: 'grid', gap: 2 }}>
+    <BreakpointsHeader />
+    <ResponsiveGridDemo />
+    <ValuesTable />
+  </Box>
+);
+
+export const ValuesOnly = () => (
+  <Box sx={{ p: 2 }}>
+    <ValuesTable />
+  </Box>
+);
+
+export const GridOnly = () => (
+  <Box sx={{ p: 2 }}>
+    <ResponsiveGridDemo />
+  </Box>
+);

package/src/stories/Theme/Colors.stories.jsx

@@ -0,0 +1,245 @@
+// src/stories/Theme/Colors.stories.jsx
+import { ThemeProvider, CssBaseline, Box, Typography, Paper, Stack, Divider, Chip } from '@mui/material';
+import { useTheme } from '@mui/material/styles';
+
+// Helpers ------------------------------------------------------------
+const Swatch = ({ label, value, subtitle, border = '1px solid rgba(0,0,0,0.08)' }) => (
+  <Paper
+    elevation={0}
+    sx={{
+      p: 1.25,
+      border,
+      minWidth: 160,
+      maxWidth: 240,
+    }}
+  >
+    <Box
+      sx={{
+        height: 44,
+        borderRadius: 1,
+        bgcolor: value,
+        border: '1px solid rgba(0,0,0,0.06)',
+      }}
+    />
+    <Typography variant="body2" sx={{ mt: 1, fontWeight: 600 }}>
+      {label}
+    </Typography>
+    <Typography variant="caption" sx={{ color: 'text.secondary' }}>
+      {subtitle || value}
+    </Typography>
+  </Paper>
+);
+
+const Row = ({ title, children }) => (
+  <Box sx={{ mb: 3 }}>
+    <Typography variant="subtitle1" sx={{ mb: 1, fontWeight: 700 }}>
+      {title}
+    </Typography>
+    <Stack direction="row" spacing={1.25} useFlexGap flexWrap="wrap">
+      {children}
+    </Stack>
+  </Box>
+);
+
+const Section = ({ title, hint, children }) => (
+  <Box sx={{ my: 3 }}>
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+      <Typography variant="h5" sx={{ fontWeight: 700 }}>
+        {title}
+      </Typography>
+      {hint ? <Chip size="small" label={hint} /> : null}
+    </Box>
+    <Divider sx={{ my: 1.5 }} />
+    {children}
+  </Box>
+);
+
+// Stories ------------------------------------------------------------
+function ColorsPreview() {
+  const theme = useTheme();
+  const border = `1px solid ${theme.custom?.border || theme.palette.divider}`;
+
+  const p = theme.palette;
+
+  return (
+    <Box sx={{ p: 2, bgcolor: 'background.default', color: 'text.primary' }}>
+      <Section title="Core Palette">
+        <Row title="Brand">
+          <Swatch label="primary.main" value={p.primary?.main} border={border} />
+          <Swatch label="secondary.main" value={p.secondary?.main} border={border} />
+          <Swatch label="icon.main" value={p.icon?.main} border={border} />
+        </Row>
+
+        <Row title="Background">
+          <Swatch label="background.default" value={p.background?.default} border={border} />
+          <Swatch label="background.paper" value={p.background?.paper} border={border} />
+          <Swatch label="background.nav" value={p.background?.nav} border={border} />
+        </Row>
+
+        <Row title="Text">
+          <Swatch label="text.primary" value={p.text?.primary} border={border} />
+          <Swatch label="text.secondary" value={p.text?.secondary} border={border} />
+          <Swatch label="divider" value={p.divider} border={border} />
+        </Row>
+
+        <Row title="Links">
+          <Swatch label="link.main" value={p.link?.main} border={border} />
+          <Swatch label="link.visited" value={p.link?.visited} border={border} />
+        </Row>
+      </Section>
+
+      <Section title="Semantic States" hint="Extended colors">
+        <Row title="Status">
+          <Swatch label="success.main" value={p.success?.main} border={border} />
+          <Swatch label="warning.main" value={p.warning?.main} border={border} />
+          <Swatch label="error.main" value={p.error?.main} border={border} />
+          <Swatch label="info.main" value={p.info?.main} border={border} />
+        </Row>
+      </Section>
+
+      <Section title="Gradients & Overlays" hint="theme.custom.*">
+        <Row title="Gradients">
+          {theme.custom?.gradients
+            ? Object.entries(theme.custom.gradients).map(([k, v]) => (
+                <Swatch key={k} label={`custom.gradients.${k}`} value="transparent" subtitle={String(v)} border={border} />
+              ))
+            : <Typography variant="body2" sx={{ color: 'text.secondary' }}>No custom.gradients defined.</Typography>}
+        </Row>
+
+        <Row title="Overlays">
+          {theme.custom?.overlays
+            ? Object.entries(theme.custom.overlays).map(([k, v]) => (
+                <Swatch key={k} label={`custom.overlays.${k}`} value="transparent" subtitle={String(v)} border={border} />
+              ))
+            : <Typography variant="body2" sx={{ color: 'text.secondary' }}>No custom.overlays defined.</Typography>}
+        </Row>
+      </Section>
+
+      <Section title="CSS Variables" hint="For non-MUI DOM usage">
+        <Row title="Auto-exported">
+          {[
+            '--gui-primary',
+            '--gui-secondary',
+            '--gui-bg-default',
+            '--gui-bg-paper',
+            '--gui-bg-nav',
+            '--gui-text-primary',
+            '--gui-text-secondary',
+            '--gui-link',
+            '--gui-link-visited',
+            '--gui-border',
+          ].map((varName) => (
+            <Paper key={varName} elevation={0} sx={{ p: 1, border }}>
+              <Typography variant="body2" sx={{ fontWeight: 600 }}>{varName}</Typography>
+              <Box sx={{ mt: 0.5, height: 24, borderRadius: 1, bgcolor: `var(${varName})`, border: '1px solid rgba(0,0,0,0.06)'}} />
+            </Paper>
+          ))}
+        </Row>
+      </Section>
+    </Box>
+  );
+}
+
+// “How to” (solo Docs): explica creación/override de tokens de color
+const HOWTO_MD = `
+### Add / Override Colors (Token-first)
+
+**1) Global token (shared across themes)**
+
+\`\`\`json
+{
+  "colors": {
+    "success": { "$type": "color", "$value": "#4caf50" },
+    "warning": { "$type": "color", "$value": "#ff9800" }
+  }
+}
+\`\`\`
+
+**2) Theme tokens (per theme)**
+
+\`\`\`json
+{
+  "color": {
+    "primary": { "$type": "color", "$value": "#0a3a42" },
+    "bgDefault": { "$type": "color", "$value": "#f8f9fa" },
+    "link": { "$type": "color", "$value": "#008c7d" }
+  },
+  "extendedColors": {
+    "error": { "$type": "color", "$value": "#f44336" },
+    "warning": { "$type": "color", "$value": "#ff9800" },
+    "success": { "$type": "color", "$value": "#4caf50" },
+    "info": { "$type": "color", "$value": "#2196f3" },
+    "gradients": {
+      "primary": { "$type": "gradient", "$value": "linear-gradient(135deg, #00aa96 0%, #008c7d 100%)" }
+    },
+    "overlays": {
+      "soft": { "$type": "color", "$value": "rgba(0,0,0,0.06)" }
+    }
+  }
+}
+\`\`\`
+
+**3) Runtime mapping**
+
+- \`color.*\` → \`theme.palette\` (brand, background, text, link, divider)
+- \`extendedColors.*\` → \`theme.palette.{success,warning,error,info}\`
+- \`extendedColors.gradients\` → \`theme.custom.gradients\`
+- \`extendedColors.overlays\` → \`theme.custom.overlays\`
+
+> Tip: si tu token aún no está mapeado a una prop nativa, puedes **exponerlo primero en** \`theme.custom.*\` y más tarde decidir su aterrizaje oficial.
+`;
+
+function HowTo() {
+  const theme = useTheme();
+  return (
+    <Box sx={{ p: 2, bgcolor: 'background.default', color: 'text.primary' }}>
+      <Typography variant="h5" sx={{ fontWeight: 700, mb: 1 }}>
+        How to add custom color tokens
+      </Typography>
+      <Divider sx={{ mb: 2 }} />
+      <Typography variant="body2" sx={{ whiteSpace: 'pre-wrap' }}>
+        {HOWTO_MD}
+      </Typography>
+    </Box>
+  );
+}
+
+// CSF ---------------------------------------------------------------
+export default {
+  title: 'Theme/Colors',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Color system driven by tokens. Reads brand, background, text, link, divider, semantic status, and extended (gradients/overlays) directly from the active theme.',
+      },
+    },
+  },
+};
+
+export const Palette = {
+  name: 'Palette & Extended',
+  render: () => <ColorsPreview />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Core palette + semantic status + extended colors (gradients, overlays) as compiled by your token engine.',
+      },
+    },
+  },
+};
+
+export const GuideCustomTokens = {
+  name: 'How to add custom tokens',
+  render: () => <HowTo />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Step-by-step guide to define global and per-theme color tokens, and how they map into the runtime theme.',
+      },
+    },
+  },
+};