ssr-emotion-react 1.0.0 → 1.0.1

package/README.md

@@ -35,8 +35,9 @@ Now, you can use not only Astro components (`.astro`) but also React JSX compone
 
 > **Note:** React JSX components in Astro Islands
 >
-> * **No directive (Server Only)**: Rendered as just static HTML tags. It results in zero client-side JavaScript. (I used to think there wasn't much point in writing static content in JSX components instead of just using Astro components. It seemed like standard Astro components was more than enough. **However, I've realized one major advantage:** SSR Emotion — the ultimate SSR Zero-Runtime CSS-in-JS solution, seamlessly integrated with Astro. By using React JSX components, your styles are automatically extracted into static CSS during the build process. This means you can enjoy the full power of CSS-in-JS while still shipping zero bytes of JS to the browser. In this regard, it's a significant upgrade over standard Astro components.)
-> * `client:only="react"` **(Client Only)**: This is the mode where the relationship between React and Astro is the clearest. It skips server-side rendering and runs entirely in the browser.
+> * **No directive (SSR Only)**: Rendered as just static HTML tags. It results in zero client-side JavaScript. (I used to think there wasn't much point in writing static content in JSX components instead of just using Astro components. It seemed like standard Astro components was more than enough. **However, I've realized one major advantage:** SSR Emotion — the ultimate SSR Zero-Runtime CSS-in-JS solution, seamlessly integrated with Astro. By using React JSX components, your styles are automatically extracted into static CSS during the build process. This means you can enjoy the full power of CSS-in-JS while still shipping zero bytes of JS to the browser. In this regard, it's a significant upgrade over standard Astro components.)
+>
+> * `client:only="react"` **(CSR Only)**: As you know, this is the standard mode where Emotion is used, and this plugin does nothing. It skips server-side rendering and runs entirely in the browser.
 >
 > * `client:load`(and others like `client:visible` or `client:idle`) **(SSR Hydration)**: Despite its cool and flashy name, "SSR Hydration" is not that complicated: it just creates a static HTML skeleton first, and once the JS is ready, the engine takes over the DOM as if it had been there from the start. If you are particular about the visual transition—like ensuring there is no layout shift by pre-setting an image's height—you might want to take control to make the swap feel completely natural.
 
@@ -48,24 +49,24 @@ This plugin wasn't originally built for React. It was first conceived as a core
 While developing [Potate](https://github.com/uniho/potate), I discovered a way to handle SSR [Emotion](https://emotion.sh/docs/@emotion/css) and Hydration that felt more "correct" for the Astro era: **The Full DOM Replacement strategy.** It worked so flawlessly in Potate that I decided to bring this lineage back to the "ancestor," React. By applying Potate's philosophy to React, we've eliminated the historical complexities of Emotion SSR and the fragility of standard React hydration.
 
 
-## 💎 The Result
+## 💎 SSR Only
+
+You don't need to learn any special properties or complex setups. It just works with the [Emotion `css()` function](https://emotion.sh/docs/@emotion/css). It feels completely natural, even in Astro's **"No directive" (SSR Only)** mode.
 
 * **Zero Runtime by default:** No `Emotion` library is shipped to the browser. It delivers a pure Zero-JS experience.
 * **Familiar DX:** Use the full expressive power of the [Emotion `css()` function](https://emotion.sh/docs/@emotion/css) that you already know.
 * **Decoupled Asset Delivery:** Styles are moved to separate `.css` files to allow for flexible cache strategies. By using unique filenames (cache busting), we ensure that updates are immediately reflected even when long-term caching is enabled on the server.
-* **Hydration Stability:** No overhead for style re-calculation. Interactive Islands remain stable and fully dynamic without visual flickering during the hydration process.
-
 
-## 🛠 How it looks
-
-In SSR Emotion, you don't need to learn any special properties or complex setups. It just works with the [Emotion `css()` function](https://emotion.sh/docs/@emotion/css). It feels completely natural, even in Astro's **"No directive" (Server Only)** mode.
+### Example: SSR Only Styling
 
 While you can use [`css()`](https://emotion.sh/docs/@emotion/css) directly, you can also create reusable functions like `flexCol()` (which we call **"The Patterns"**).
 
 ```jsx
+// src/components/StaticBox.jsx
+
 import { css } from '@emotion/css'
 
-export const MyComponent = () => (
+export default props => (
   <div class={flexCol({ 
     color: 'hotpink',
     '&:hover': { color: 'deeppink' }
@@ -81,10 +82,27 @@ const flexCol = (...args) => css({
 
 ```
 
+```astro
+---
+// src/pages/index.astro
 
-## 🌗 Hybrid Styling (SSR + CSR)
+import Layout from '../layouts/Layout.astro'
+import StaticBox from '../components/StaticBox'
+---
 
-In Astro, Island components (`client:*`) get the best of both worlds.
+<Layout>
+  <StaticBox />
+</Layout>
+
+```
+
+## 🌗 SSR Hydration (SSR + CSR)
+
+In Astro, Island components (`client:load` and others) get the best of both worlds.
+
+* **Hydration Stability:** No overhead for style re-calculation. Interactive Islands remain stable and fully dynamic without visual flickering during the hydration process.
+* **Unlimited Flexibility:** Need to change colors based on user input or mouse position? Just pass the props/state to css() like you always do.
+* **Zero Learning Curve:** If you know how to use useEffect and Emotion, you already know how to build dynamic Islands with React.
 
 ### How it works
 
@@ -103,12 +121,12 @@ You can easily change styles when the component "wakes up" in the browser:
 ```jsx
 // src/components/InteractiveBox.jsx
 
-export const InteractiveBox = () => {
-  const [isLoaded, setIsLoaded] = useState(false);
+export default props => {
+  const [isLoaded, setIsLoaded] = useState(false)
 
   useEffect(() => {
-    setIsLoaded(true); // Triggers once JS is active
-  }, []);
+    setIsLoaded(true) // Triggers once JS is active
+  }, [])
 
   return (
     <div class={css({
@@ -119,8 +137,8 @@ export const InteractiveBox = () => {
     })}>
       {isLoaded ? 'I am Interactive!' : 'I am Static HTML'}
     </div>
-  );
-};
+  )
+}
 
 ```
 
@@ -128,9 +146,9 @@ export const InteractiveBox = () => {
 ---
 // src/pages/index.astro
 
-import Layout from '../layouts/Layout.astro';
-import StaticBox from '../components/StaticBox';
-import InteractiveBox from '../components/InteractiveBox';
+import Layout from '../layouts/Layout.astro'
+import StaticBox from '../components/StaticBox'
+import InteractiveBox from '../components/InteractiveBox'
 ---
 
 <Layout>
@@ -140,13 +158,6 @@ import InteractiveBox from '../components/InteractiveBox';
 
 ```
 
-### Key Benefits
-
-* **No FOUC (Flash of Unstyled Content):** Since the "Server Side" style is already in the static CSS, there's no flickering.
-* **Unlimited Flexibility:** Need to change colors based on user input or mouse position? Just pass the props/state to css() like you always do.
-* **Zero Learning Curve:** If you know how to use useEffect and Emotion, you already know how to build dynamic Islands with React.
-
-
 ## 🛠 The Patterns 
 
 We refer to reusable CSS logic as "The Patterns".
@@ -172,7 +183,9 @@ const linkOverlay = (...args) => css({
   },
 }, ...args)
 
-export default props => (
+:
+
+const MyComponent = props => (
   // The parent must have position: relative
   <div class={css({ position: 'relative', border: '1px solid #ccc', padding: '1rem' })}>
     <img src="https://via.placeholder.com/150" alt="placeholder" />
@@ -198,11 +211,13 @@ const isBP = value => value in BP
 const _gt = bp => `(min-width: ${isBP(bp) ? BP[bp] : bp})`
 const _lt = bp => `(max-width: ${isBP(bp) ? BP[bp] : bp})`
 
-const gt = (bp, ...args) => css({[`@media ${_gt(bp)}`]: args})
-const lt = (bp, ...args) => css({[`@media ${_lt(bp)}`]: args})
-const bw = (min, max, ...args) => css({[`@media ${_gt(min)} and ${_lt(max)}`]: args})
+const gt = (bp, ...args) => css({[`@media ${_gt(bp)}`]: css(...args)})
+const lt = (bp, ...args) => css({[`@media ${_lt(bp)}`]: css(...args)})
+const bw = (min, max, ...args) => css({[`@media ${_gt(min)} and ${_lt(max)}`]: css(...args)})
 
-export default props => (
+:
+
+const MyComponent = props => (
   <div class={css(
     { color: 'black' }, // default css
     bw('sm', '75rem', { color: 'blue' }), // between
@@ -230,7 +245,7 @@ export const styled = (Tag) => (style, ...values) => props => {
   const makeClassName = (style, ...values) =>
     typeof style == 'function' ? makeClassName(style(props)) : css(style, ...values);
  
-  const {sx, className, 'class': _class, children, ...wosx} = props;
+  const {as: As, sx, className, 'class': _class, children, ...wosx} = props;
 
   // cleanup transient props
   Object.keys(wosx).forEach(key => {
@@ -242,7 +257,8 @@ export const styled = (Tag) => (style, ...values) => props => {
     className: cx(makeClassName(style, ...values), makeClassName(sx), _class, className),
   };
 
-  return (<Tag {...newProps}>{children}</Tag>);
+  const T = As || Tag;
+  return (<T {...newProps}>{children}</T>);
 };
 
 ```
@@ -251,26 +267,23 @@ What is the sx prop? For those unfamiliar with libraries like [MUI, the sx prop]
 
 In this implementation, you can pass raw style objects to the sx prop without wrapping them in `css()` or "The Patterns" functions.
 
-However, since the underlying tag of a button is not always `<button>`, and because using something like `createElement()` locally is generally not recommended, I personally prefer the approach shown below. In any case, how you choose to implement this is entirely up to you.
+However, defining a `styled` component inside a render function is **a pitfall** because it creates a new component identity every time, forcing React to re-mount.
+I personally prefer the approach shown below. In any case, how you choose to implement this is entirely up to you.
 
 ```js
-// the-sx-prop.js
+// the-sx-prop.jsx
 
 import {css, cx} from '@emotion/css'
 
-const sx = (props, ...styles) => {
-  const result = typeof props === 'object' ? {...props} : {};
-  const _css = [];
-  for (let arg of styles) {
-    if (typeof arg === 'function') {
-      _css.push(arg(result));
-    } else if (arg) {
-      _css.push(arg);
-    }
+export const sx = (props, style, ...values) => {
+  let result = (props && typeof props === 'object' ? props : {});
+  if (typeof style === 'function') {
+    result = {...style(result), ...result};
+    result.className = cx(css(result?.$css, ...values), result.className);
+  } else {
+    result.className = cx(css(style, ...values), result.className);
   }
 
-  result.className = cx(css(_css), result.className);
-
   // cleanup transient props
   Object.keys(result).forEach(key => {
     if (key.startsWith('$')) delete result[key];
@@ -279,12 +292,11 @@ const sx = (props, ...styles) => {
   return result;
 }
 
-export default sx;
-
-// Factory for component-scoped sx functions
+// Factory for component-scoped sx functions (adds `.css()` automatically)
 sx._factory = (genCSS) => {
-  const f = (props, ...styles) => sx(props, ...styles, genCSS);
-  f.css = (...styles) => f({}, ...styles); // Styles-only function when you don't need props
+  const f = (props, ...styles) => sx(props || {}, genCSS, ...styles);
+  f.css = (...styles) => f({}, ...styles); // style only
+  // f.curry = (props) => (...values) => f(props || {}, ...values); // currying
   return f;
 }
 
@@ -308,7 +320,7 @@ sx.button = sx._factory(props => {
     style.boxShadow = 'var(--style-shadows-level1)';
   }
 
-  return [
+  return {$css: [
     css`
       line-height: 1;
       display: inline-flex;
@@ -319,13 +331,13 @@ sx.button = sx._factory(props => {
       }
     `,
     style,
-  ];
+  ]};
 });
 
 ```
 
 ```jsx
-import sx from './the-sx-prop'
+import {sx} from './the-sx-prop'
 
 export default props => {
   return (<>
@@ -340,6 +352,59 @@ export default props => {
 
 ```
 
+Furthermore, by creating a component like the one below, you evolve into a **Super Saiyan** (for those who aren't familiar, it's like a classic Superman).
+
+```js
+// the-sx-prop.jsx
+
+:
+:
+
+export const As = ({as: Tag = 'div', children, ...props}) => <Tag {...props}>{children}</Tag>;
+
+// My list style
+sx.ul = sx._factory(props => ({
+  as: 'ul',
+  $css: css`
+  & > li {
+    position: relative;
+    padding-left: 1.5rem;
+
+    &:before {
+      content: "\\2022";
+      position: absolute;
+      width: 1.5rem;
+      left: 0; top: 0;
+      text-align: center;
+    }
+    & + li, & > ul {
+      margin-top: .25rem;
+    }
+  }
+  & > ul {
+    margin-left: 1rem;
+  }
+`}));
+
+```
+
+```jsx
+import {sx, As} from './the-sx-prop'
+
+const MyComponent = props => {
+  return (
+  <As {...sx.ul.css({ padding: '20px', border: '1px solid #ccc' })}>
+    <li>Is it Flexible?</li>
+    <li>Is it Dynamic?</li>
+    <li>Is it Polymorphic?</li>
+    <li>No, it's <strong>As</strong>!</li>
+  </As>
+  )
+}
+
+```
+
+
 ## 🚫 Won't Do
 
 The following features are not planned for the core roadmap (though contributors are welcome to explore them):