Add composable systems!

Author: RoyalIcing

apps/components_guide_web/lib/components_guide_web/controllers/composable_systems_controller.ex

@@ -0,0 +1,18 @@
+defmodule ComponentsGuideWeb.ComposableSystemsController do
+  use ComponentsGuideWeb, :controller
+  require Logger
+
+  def index(conn, _params) do
+    render(conn, "index.html", article: "intro")
+  end
+
+  @articles ["opinionated-vs-flexible"]
+
+  def show(conn, %{"id" => article}) when article in @articles do
+    render(conn, "index.html", article: article)
+  end
+
+  def show(conn, _params) do
+    raise Phoenix.Router.NoRouteError, conn: conn, router: ComponentsGuideWeb.Router
+  end
+end

apps/components_guide_web/lib/components_guide_web/router.ex

@@ -29,6 +29,10 @@ defmodule ComponentsGuideWeb.Router do
               AccessibilityFirstController,
               only: [:index, :show]
 
+    resources "/composable-systems",
+              ComposableSystemsController,
+              only: [:index, :show]
+
     live "/color", ColorLive, :index
     live "/color/:definition", ColorLive, :show
     live "/color/lab/:definition", ColorLive, :lab

apps/components_guide_web/lib/components_guide_web/templates/composable_systems/_header.html.eex

@@ -0,0 +1,3 @@
+<header class="text-white text-shadow" style="<%= header_styles() %>">
+  <%= render ComponentsGuideWeb.ComposableSystemsView, "_top.html" %>
+</header>

apps/components_guide_web/lib/components_guide_web/templates/composable_systems/_nav.html.eex

@@ -0,0 +1,8 @@
+<nav class="pt-6 pb-4">
+  <ul y-y x-x=md class="text-lg font-bold" style="--link-padding: 0.75em">
+    <li><%= link("Why?", to: '/composable-systems') %>
+    <li><%= link("Opinionated vs Flexible", to: '/composable-systems/opinionated-vs-flexible') %>
+    <li><%= link("Single Responsibility", to: '/composable-systems/roles') %>
+    <li><%= link("Deterministic", to: '/composable-systems/roles') %>
+  </ul>
+</nav>

apps/components_guide_web/lib/components_guide_web/templates/composable_systems/_top.html.eex

@@ -0,0 +1,7 @@
+<div class="mx-auto max-w-4xl">
+  <h1 y-y x-x=md class="pt-8 row space-x-4 text-4xl text-center font-bold leading-tight">
+    <span class="mr-2 text-4xl">🖇🍀</span>
+    <span><%= "Composable Systems" %></span>
+  </h1>
+  <%= render ComponentsGuideWeb.ComposableSystemsView, "_nav.html" %>
+</div>

apps/components_guide_web/lib/components_guide_web/templates/composable_systems/index.html.eex

@@ -0,0 +1,9 @@
+<%= render @view_module, "_header.html" %>
+
+<article>
+  <div class="text-white bg-gray-900">
+    <div class="content max-w-4xl mx-auto py-8 text-xl">
+      <%= render(@view_module, @article <> ".html", conn: @conn) %>
+    </div>
+  </div>
+</article>

apps/components_guide_web/lib/components_guide_web/templates/composable_systems/intro.html.md

@@ -0,0 +1,5 @@
+# Why Think in Composable Systems?
+
+- Less to explain at once
+- Reuse more
+- Composable encourages simplicity

apps/components_guide_web/lib/components_guide_web/templates/composable_systems/opinionated-vs-flexible.html.md

@@ -0,0 +1,39 @@
+# Opinionated vs Flexible
+
+If something is opinionated and well-designed, then it guides the user on a clear path to success. The system should inform the user as they build.
+
+If something is flexible, then it allows the users to do what they like. They are not blocked from achieving essential results.
+
+SwiftUI is an example of a system that is very flexible. Modifiers can be added to *any* element. Animation can be used to enhance property changes into transitions. However, it’s not flexible to the point that it’s hard to make something that looks and acts like an app. It provides opinions: system controls that adapt to the platform, the reactive Combine library, recommended font sizes that adjust to the user’s preference with Dynamic Type, just to name a few examples.
+
+## Too flexible
+
+If something is *too* flexible, it’s harder to learn. There’s a lot more cognitive load. It can be hard to form a picture in the mind of how it works. There could be multiple ways of making the same thing, and it could be unclear of which one is best.
+
+Flexibility often begets changes to allow more flexibility. A little bit of flexibility gives way to even more, and soon the system is large enough that it’s difficult to understand.
+
+Redux is an example of something that is extremely flexible. The functional style of the reducers allured to simplicity, but the rest of the system leaves a lot of questions unanswered. “Do I put this sort of code in the action or the connected component? Do I pass this state when the action is dispatched, or do I read from the store in my action? What sort of state do I store in a reducer: transient local, remote cache, local state to be sent to the remote?”
+
+## Too opinionated
+
+Opinionated without explanation produces confusion and frustration.
+
+Too opinionated leads to an awkward or limited solution being provided when there’s an obvious, better suited approach just out of reach.
+
+Too opinionated means *hacks* are needed to get the system to work as desired. Hacks often lead to bugs, or make things hard to change in the future.
+
+Poorly opinionated mean that the language of the system doesn’t work well with the language of the constructors.
+
+## Flexible enough
+
+Enough flexibility should allow the user to achieve what they want without being overwhelmed. They shouldn’t need to resort to hacks to get something working.
+
+Progressive disclosure can allow a system to provide a small surface area to get started with successfully, and then has extra discoverable aspects that allow more nuanced and specific behaviour.
+
+## Opinionated enough
+
+Enough opinions should be provided so that the team of constructors is able to be aligned with the manufacturers. What they make should be consistent. They should be lead into the pit of success.
+
+Two people given the same problem using your system should ideally come up with similar solutions. If their solutions are completely different, then there’s a communication or flexibility or other problem with your system. A solid start to an idea should be gleamed when reading the documentation for your system.
+
+Hard common problems should either be answered with a clear and convincing solution, or explicitly be highlighted as being left to the team to come up with their own solution (likely using a flexible system).

apps/components_guide_web/lib/components_guide_web/templates/landing/index.html.eex

@@ -53,6 +53,10 @@ subhead = "Guides to accessibility, TDD, BDD, naming, performance, and the lates
   <%= render ComponentsGuideWeb.AccessibilityFirstView, "_top.html" %>
 </article>
 
+<article class="text-white text-shadow py-6" style="<%= sections_styles(:orange) %>">
+  <%= render ComponentsGuideWeb.ComposableSystemsView, "_top.html" %>
+</article>
+
 <div hidden class="text-white">
   <section class="pt-20 pb-20" style="<%= sections_styles(:dark) %>">
     <header class="mb-8 mx-auto max-w-4xl px-2 text-center">

apps/components_guide_web/lib/components_guide_web/views/composable_systems_view.ex

@@ -0,0 +1,24 @@
+defmodule ComponentsGuideWeb.ComposableSystemsView do
+  use ComponentsGuideWeb, :view
+  require EEx
+
+  def header_styles() do
+    l = 62
+    a = 51
+    b = 24
+
+    color = {:lab, l, a, b}
+
+    gradient =
+      Styling.linear_gradient("150grad", [
+        {:lab, l * 1.5, a * 0.7, b * 2},
+        {:lab, l * 1.3, a * 0.8, b * 1.6},
+        {:lab, l * 1.1, a * 0.9, b * 1.2},
+        color,
+        {:lab, l * 0.9, a * 1.3, b * 0.7},
+        {:lab, l * 0.8, a * 1.7, b * 0.5}
+      ])
+
+    "background-color: #{color |> Styling.to_css()}; background-image: #{gradient};"
+  end
+end