wip

DaniGuardiola · Jul 24, 2024 · f32cea0 · f32cea0
1 parent db13cdd
commit f32cea0
Show file tree

Hide file tree

Showing 2 changed files with 151 additions and 36 deletions.
diff --git a/src/components/MDXContent/styles.sass b/src/components/MDXContent/styles.sass
@@ -95,3 +95,15 @@
 
   .dark & input
     color-scheme: dark
+
+  & table
+    @apply w-full
+
+    & tr
+      @apply m-0 border-t p-0
+
+    & :is(td, th)
+      @apply border border-black/50 dark:border-white/60 px-4 py-2 text-left [&[align=center]]:text-center [&[align=right]]:text-right
+
+    & th
+      @apply font-bold
diff --git a/src/routes/article/compound-components/index.mdx b/src/routes/article/compound-components/index.mdx
@@ -10,7 +10,7 @@ topics:
   - frontend
 ---
 
-# Namespacing
+# Namespaces
 
 ## Flat
 
@@ -48,7 +48,7 @@ topics:
 </Menu>
 ```
 
-# Export styles
+# Exports
 
 ## Named
 
@@ -62,17 +62,27 @@ export function MenuButton() {}
 
 ```tsx
 export const Menu = {
-  root: function MenuRoot() {},
-  button: function MenuButton() {},
+  Root: function MenuRoot() {},
+  Button: function MenuButton() {},
   // ...
 };
 ```
 
 > Note: `export default {}` is also possible, but [not ideal](https://blog.piotrnalepa.pl/2020/06/26/default-exports-vs-named-exports/).
 
-# Import styles
+## Overloaded
 
-## Flat
+```tsx
+export function Menu() {}
+Menu.Button = function MenuButton() {};
+// ...
+```
+
+> Note: `export default function ...` is also possible, but [not ideal](https://blog.piotrnalepa.pl/2020/06/26/default-exports-vs-named-exports/).
+
+# Imports
+
+## Named
 
 ```tsx
 import { Menu, MenuButton } from "ui-package";
@@ -105,79 +115,172 @@ import * as UI from "ui-package";
 </UI.Menu>;
 ```
 
-## Overloaded
+# Options
 
-```tsx
-import { Menu } from "ui-package";
+## Flat + named export
 
-<Menu>
-  <Menu.Button />
-  {/* ... */}
-</Menu>;
+```tsx
+// Menu.tsx
+export function Menu() {}
+export function MenuButton() {}
 ```
 
-# Combinations
+Pros and cons:
 
-## Flat
+| Score | Description            | Notes                                                                                                               |
+| ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| ✅    | Tree-shakable          | In all import styles, most bundler tools will tree-shake unused component parts.                                    |
+| ✅    | Auto-imports           | IDEs will automatically import the components (or parts) you use.                                                   |
+| ❌    | Component autocomplete | At most, you can start typing the name of the component (e.g. "Menu") to filter out other suggestions.              |
+| 🟠    | Library autocomplete   | The library namespace contains all parts of all components, making it hard to see available components at a glance. |
+
+Supports:
 
 ```tsx
+// named import
+import { Menu, MenuButton } from "ui-package"; // or "ui-package/menu"
+
 <Menu>
   <MenuButton />
-</Menu>
+</Menu>;
 ```
 
-### Named export + flat import
-
 ```tsx
-// Menu.tsx
-export function Menu() {}
-export function MenuButton() {}
+// global "as" import
+import * as UI from "ui-package";
+
+<UI.Menu>
+  <UI.MenuButton />
+</UI.Menu>;
 ```
 
+Also this (but ew):
+
 ```tsx
-// App.tsx
-import { Menu, MenuButton } from "ui-package";
+// local "as" import
+import * as Menu from "ui-package/menu";
 
-<Menu>
-  <MenuButton />
-</Menu>;
+<Menu.Menu>
+  <Menu.MenuButton />
+</Menu.Menu>;
 ```
 
-### Named export + local "as" import
+## Dot + named export
 
-> Naming improved for readability:
->
-> - `Menu` -> `Root`
-> - `MenuButton` -> `Button`
+| Score | Description            | Notes                                                                                                                              |
+| ----- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| ✅    | Tree-shakable          | This is the only option for dot namespacing that is tree-shakable.                                                                 |
+| ❌    | Auto-imports           | Users need to manually write the local "as" import every time.                                                                     |
+| ✅    | Component autocomplete | Suggestions for all parts (and only the parts) will show up after the dot.                                                         |
+| ❌    | Library autocomplete   | It's not possible to re-export at the top level since that'd cause conflicts (e.g. multiple `Root` parts of different components). |
 
 ```tsx
 // Menu.tsx
 export function Root() {}
 export function Button() {}
 ```
 
+Supports:
+
 ```tsx
-// App.tsx
+// local "as" import
 import * as Menu from "ui-package/menu";
 
 <Menu.Root>
   <Menu.Button />
 </Menu.Root>;
 ```
 
-### Named export + global "as" import
+## Dot + object export
+
+```tsx
+// Menu.tsx
+export const Menu = {
+  Root: function MenuRoot() {},
+  Button: function MenuButton() {},
+};
+```
+
+| Score | Description            | Notes                                                                                         |
+| ----- | ---------------------- | --------------------------------------------------------------------------------------------- |
+| ❌    | Tree-shakable          | Since it's exported as a single object, it's not tree-shakable.                               |
+| ✅    | Auto-imports           | IDEs will automatically import the components you use.                                        |
+| ✅    | Component autocomplete | Suggestions for all parts (and only the parts) will show up after the dot.                    |
+| ✅    | Library autocomplete   | Only the components (objects) will show up in the library autocomplete (and not their parts). |
+
+Supports:
+
+```tsx
+// named import
+import { Menu } from "ui-package"; // or "ui-package/menu"
+
+<Menu.Root>
+  <Menu.Button />
+</Menu.Root>;
+```
+
+```tsx
+// global "as" import
+import * as UI from "ui-package";
+
+<UI.Menu.Root>
+  <UI.Menu.Button />
+</UI.Menu.Root>;
+```
+
+Also this (but ew):
+
+```tsx
+// local "as" import
+import * as Menu from "ui-package/menu";
+
+<Menu.Menu.Root>
+  <Menu.Menu.Button />
+</Menu.Menu.Root>;
+```
+
+## Overloaded
 
 ```tsx
 // Menu.tsx
 export function Menu() {}
-export function MenuButton() {}
+Menu.Button = function MenuButton() {};
 ```
 
+| Score | Description            | Notes                                                                                                                                              |
+| ----- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ❌    | Tree-shakable          | Since it's exported as a single function with properties, it's not tree-shakable.                                                                  |
+| ✅    | Auto-imports           | IDEs will automatically import the components you use.                                                                                             |
+| 🟠    | Component autocomplete | Suggestions for all parts will show up after the dot. Unfortunately, so will the function prototype methods and properties (`apply`, `call`, etc). |
+| ✅    | Library autocomplete   | Only the root components will show up in the library autocomplete (and not their parts).                                                           |
+
+Supports:
+
 ```tsx
-// App.tsx
+// named import
+import { Menu } from "ui-package"; // or "ui-package/menu"
+
+<Menu>
+  <Menu.Button />
+</Menu>;
+```
+
+```tsx
+// global "as" import
 import * as UI from "ui-package";
 
 <UI.Menu>
-  <UI.MenuButton />
+  <UI.Menu.Button />
 </UI.Menu>;
 ```
+
+Also this (but ew):
+
+```tsx
+// local "as" import
+import * as Menu from "ui-package/menu";
+
+<Menu.Menu>
+  <Menu.Menu.Button />
+</Menu.Menu>;
+```