yattho_view_components 0.0.1

data/app/components/yattho/alpha/layout.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module Yattho
+  module Alpha
+    # `Layout` provides foundational patterns for responsive pages.
+    # `Layout` can be used for simple two-column pages, or it can be nested to provide flexible 3-column experiences.
+    #  On smaller screens, `Layout` uses vertically stacked rows to display content.
+    #
+    # `Layout` flows as both column, when there's enough horizontal space to render both `Main` and `Sidebar`side-by-side (on a desktop of tablet device, per instance);
+    # or it flows as a row, when `Main` and `Sidebar` are stacked vertically (e.g. on a mobile device).
+    # `Layout` should always work in any screen size.
+    #
+    # @accessibility
+    #   Keyboard navigation follows the markup order. Decide carefully how the focus order should be be by deciding whether
+    #   `main` or `sidebar` comes first in code. The code order won’t affect the visual position.
+    class Layout < Yattho::Component
+      status :alpha
+
+      FIRST_IN_SOURCE_DEFAULT = :sidebar
+      FIRST_IN_SOURCE_OPTIONS = [FIRST_IN_SOURCE_DEFAULT, :main].freeze
+
+      SIDEBAR_COL_PLACEMENT_DEFAULT = :start
+      SIDEBAR_COL_PLACEMENT_OPTIONS = [SIDEBAR_COL_PLACEMENT_DEFAULT, :end].freeze
+
+      GUTTER_DEFAULT = :default
+      GUTTER_MAPPINGS = {
+        :none => "Layout--gutter-none",
+        :condensed => "Layout--gutter-condensed",
+        :spacious => "Layout--gutter-spacious",
+        GUTTER_DEFAULT => ""
+      }.freeze
+      GUTTER_OPTIONS = GUTTER_MAPPINGS.keys.freeze
+
+      STACKING_BREAKPOINT_DEFAULT = :md
+      STACKING_BREAKPOINT_MAPPINGS = {
+        :sm => "",
+        STACKING_BREAKPOINT_DEFAULT => "Layout--flowRow-until-md",
+        :lg => "Layout--flowRow-until-lg"
+      }.freeze
+      STACKING_BREAKPOINT_OPTIONS = STACKING_BREAKPOINT_MAPPINGS.keys.freeze
+
+      SIDEBAR_ROW_PLACEMENT_DEFAULT = :start
+      SIDEBAR_ROW_PLACEMENT_OPTIONS = [SIDEBAR_ROW_PLACEMENT_DEFAULT, :end, :none].freeze
+
+      SIDEBAR_WIDTH_DEFAULT = :default
+      SIDEBAR_WIDTH_MAPPINGS = {
+        SIDEBAR_WIDTH_DEFAULT => "",
+        :narrow => "Layout--sidebar-narrow",
+        :wide => "Layout--sidebar-wide"
+      }.freeze
+      SIDEBAR_WIDTH_OPTIONS = SIDEBAR_WIDTH_MAPPINGS.keys.freeze
+
+      # The layout's main content.
+      #
+      # @param width [Symbol] <%= one_of(Yattho::Alpha::Layout::Main::WIDTH_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :main, "Yattho::Alpha::Layout::Main"
+
+      # The layout's sidebar.
+      #
+      # @param width [Symbol] <%= one_of(Yattho::Alpha::Layout::SIDEBAR_WIDTH_OPTIONS) %>
+      # @param col_placement [Symbol] Sidebar placement when `Layout` is in column modes. <%= one_of(Yattho::Alpha::Layout::SIDEBAR_COL_PLACEMENT_OPTIONS) %>
+      # @param row_placement [Symbol] Sidebar placement when `Layout` is in row mode. <%= one_of(Yattho::Alpha::Layout::SIDEBAR_ROW_PLACEMENT_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :sidebar, lambda { |
+        width: SIDEBAR_WIDTH_DEFAULT,
+        col_placement: SIDEBAR_COL_PLACEMENT_DEFAULT,
+        row_placement: SIDEBAR_ROW_PLACEMENT_DEFAULT,
+        **system_arguments
+      |
+        # These classes have to be set in the parent `Layout` element, so we modify its system arguments.
+        @system_arguments[:classes] = class_names(
+          @system_arguments[:classes],
+          "Layout--sidebarPosition-#{fetch_or_fallback(SIDEBAR_COL_PLACEMENT_OPTIONS, col_placement,
+                                                       SIDEBAR_COL_PLACEMENT_DEFAULT)}",
+          "Layout--sidebarPosition-flowRow-#{fetch_or_fallback(SIDEBAR_ROW_PLACEMENT_OPTIONS, row_placement,
+                                                               SIDEBAR_ROW_PLACEMENT_DEFAULT)}",
+          SIDEBAR_WIDTH_MAPPINGS[fetch_or_fallback(SIDEBAR_WIDTH_OPTIONS, width, SIDEBAR_WIDTH_DEFAULT)]
+        )
+
+        Yattho::Alpha::Layout::Sidebar.new(**system_arguments)
+      }
+
+      # @example Default
+      #
+      #   <%= render(Yattho::Alpha::Layout.new) do |component| %>
+      #     <% component.with_main(border: true) { "Main" } %>
+      #     <% component.with_sidebar(border: true) { "Sidebar" } %>
+      #   <% end %>
+      #
+      # @example Main widths
+      #
+      #   @description
+      #     When `full`, the main column will stretch to cover all the available width.
+      #     Otherwise, the main column will try to be centered in the screen; it may appear aligned to the left when there isn't enough space.
+      #
+      #     Use smaller maximum widths in the main column to facilitate interface scanning and reading.
+      #
+      #     When flowing as a row, `Main` takes the full width.
+      #
+      #   @code
+      #     <%= render(Yattho::Alpha::Layout.new) do |component| %>
+      #       <% component.with_main(width: :full, border: true) { "Main" } %>
+      #       <% component.with_sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new(mt: 5)) do |component| %>
+      #       <% component.with_main(width: :md, border: true) { "Main" } %>
+      #       <% component.with_sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new(mt: 5)) do |component| %>
+      #       <% component.with_main(width: :lg, border: true) { "Main" } %>
+      #       <% component.with_sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new(mt: 5)) do |component| %>
+      #       <% component.with_main(width: :xl, border: true) { "Main" } %>
+      #       <% component.with_sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @example Sidebar widths
+      #
+      #   @description
+      #     Sets the sidebar width. The width is predetermined according to the breakpoint instead of it being percentage-based.
+      #
+      #     - `default`: [md: 256px, lg: 296px, xl: 320px]
+      #     - `narrow`: [md: 240px, lg: 256px, xl: 296px]
+      #     - `wide`: [md: 296px, lg: 320px, xl: 344px]
+      #
+      #     When flowing as a row, `Sidebar` takes the full width.
+      #
+      #   @code
+      #     <%= render(Yattho::Alpha::Layout.new) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(width: :default, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new(mt: 5)) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(width: :narrow, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new(mt: 5)) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(width: :wide, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @example Sidebar placement
+      #
+      #   @description
+      #     Use `start` for sidebars that manipulate local navigation, while right-aligned `end` is useful for metadata and other auxiliary information.
+      #
+      #   @code
+      #     <%= render(Yattho::Alpha::Layout.new) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(col_placement: :start, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new( mt: 5)) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(col_placement: :end, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @example Sidebar placement as row
+      #
+      #   @description
+      #     When flowing as a row, whether the sidebar is rendered first or last in the layout, or, if it's entirely hidden from the user.
+      #
+      #     When `hidden`, make sure the experience is not degraded on smaller screens, and the user can still access the sidebar content somehow.
+      #     For instance, the user may not see a Settings navigation sidebar when drilled down on a page, but they can still navigate to the Settings
+      #     landing page to interact with the local navigation.
+      #
+      #   @code
+      #     <%= render(Yattho::Alpha::Layout.new) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(row_placement: :start, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new(mt: 5)) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(row_placement: :end, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new(mt: 5)) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(row_placement: :none, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @example Changing when to render `Layout` as columns
+      #
+      #   @description
+      #     You can specify when the `Layout` should change from rows into columns.
+      #     Any screen size before this breakpoint will render the `Layout` in stacked rows.
+      #
+      #   @code
+      #     <%= render(Yattho::Alpha::Layout.new(stacking_breakpoint: :sm)) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new(stacking_breakpoint: :md, mt: 5)) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Yattho::Alpha::Layout.new(stacking_breakpoint: :lg, mt: 5)) do |component| %>
+      #       <% component.with_main(border: true) { "Main" } %>
+      #       <% component.with_sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @param stacking_breakpoint [Symbol] When the `Layout` should change from rows into columns. <%= one_of(Yattho::Alpha::Layout::STACKING_BREAKPOINT_OPTIONS) %>
+      # @param first_in_source [Symbol] Which element to render first in the HTML. This will change the keyboard navigation order. <%= one_of(Yattho::Alpha::Layout::FIRST_IN_SOURCE_OPTIONS) %>
+      # @param gutter [Symbol] The amount of space between the main section and the sidebar. <%= one_of(Yattho::Alpha::Layout::GUTTER_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(stacking_breakpoint: STACKING_BREAKPOINT_DEFAULT, first_in_source: FIRST_IN_SOURCE_DEFAULT,
+                     gutter: :default, **system_arguments)
+        @first_in_source = fetch_or_fallback(FIRST_IN_SOURCE_OPTIONS, first_in_source, FIRST_IN_SOURCE_OPTIONS)
+
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
+          "Layout",
+          STACKING_BREAKPOINT_MAPPINGS[fetch_or_fallback(STACKING_BREAKPOINT_OPTIONS, stacking_breakpoint,
+                                                         STACKING_BREAKPOINT_DEFAULT)],
+          GUTTER_MAPPINGS[fetch_or_fallback(GUTTER_OPTIONS, gutter, GUTTER_DEFAULT)],
+          system_arguments[:classes]
+        )
+      end
+
+      def render?
+        main? && sidebar?
+      end
+
+      # The layout's main content.
+      class Main < Yattho::Component
+        WIDTH_DEFAULT = :full
+        WIDTH_OPTIONS = [WIDTH_DEFAULT, :md, :lg, :xl].freeze
+
+        TAG_DEFAULT = :div
+        TAG_OPTIONS = [TAG_DEFAULT, :main].freeze
+
+        # @param width [Symbol] <%= one_of(Yattho::Alpha::Layout::Main::WIDTH_OPTIONS) %>
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(tag: TAG_DEFAULT, width: WIDTH_DEFAULT, **system_arguments)
+          @width = fetch_or_fallback(WIDTH_OPTIONS, width, WIDTH_DEFAULT)
+
+          @system_arguments = system_arguments
+          @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, TAG_DEFAULT)
+          @system_arguments[:classes] = class_names(
+            "Layout-main",
+            system_arguments[:classes]
+          )
+        end
+
+        def call
+          render(Yattho::BaseComponent.new(**@system_arguments)) do
+            if @width == :full
+              content
+            else
+              render(Yattho::BaseComponent.new(tag: :div, classes: "Layout-main-centered-#{@width}")) do
+                render(Yattho::BaseComponent.new(tag: :div, container: @width)) do
+                  content
+                end
+              end
+            end
+          end
+        end
+      end
+
+      # The layout's sidebar content.
+      class Sidebar < Yattho::Component
+        TAG_DEFAULT = :div
+        TAG_OPTIONS = [TAG_DEFAULT, :aside, :nav, :section].freeze
+
+        def initialize(tag: TAG_DEFAULT, **system_arguments)
+          @system_arguments = system_arguments
+
+          @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, TAG_DEFAULT)
+          @system_arguments[:classes] = class_names(
+            "Layout-sidebar",
+            @system_arguments[:classes]
+          )
+        end
+
+        def call
+          render(Yattho::BaseComponent.new(**@system_arguments)) { content }
+        end
+      end
+    end
+  end
+end

data/app/components/yattho/alpha/menu.css

@@ -0,0 +1,117 @@
+/* menu */
+
+/* A menu on the side of a page, defaults to left side. e.g. github.com/about */
+
+.menu {
+  margin-bottom: var(--yattho-stack-gap-normal, 16px);
+  list-style: none;
+  background-color: var(--color-canvas-default);
+  border: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-default);
+  border-radius: var(--yattho-borderRadius-medium, 6px);
+}
+
+.menu-item {
+  position: relative;
+  display: block;
+  padding: var(--yattho-control-medium-paddingInline-condensed, 8px) var(--yattho-control-medium-paddingInline-spacious, 16px);
+  color: var(--color-fg-default);
+  border-bottom: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-muted);
+}
+
+.menu-item:first-child {
+    border-top: 0;
+    border-top-left-radius: var(--yattho-borderRadius-medium, 6px);
+    border-top-right-radius: var(--yattho-borderRadius-medium, 6px);
+  }
+
+.menu-item:first-child::before {
+      border-top-left-radius: var(--yattho-borderRadius-medium, 6px);
+    }
+
+.menu-item:last-child {
+    border-bottom: 0;
+    border-bottom-right-radius: var(--yattho-borderRadius-medium, 6px);
+    border-bottom-left-radius: var(--yattho-borderRadius-medium, 6px);
+  }
+
+.menu-item:last-child::before {
+      border-bottom-left-radius: var(--yattho-borderRadius-medium, 6px);
+    }
+
+.menu-item:hover {
+    text-decoration: none;
+    background-color: var(--color-neutral-subtle);
+  }
+
+.menu-item:active {
+    background-color: var(--color-canvas-subtle);
+  }
+
+.menu-item.selected,
+  .menu-item[aria-selected='true'],
+  .menu-item[aria-current]:not([aria-current='false']) {
+    cursor: default;
+    background-color: var(--color-menu-bg-active);
+  }
+
+.menu-item.selected::before, .menu-item[aria-selected='true']::before, .menu-item[aria-current]:not([aria-current='false'])::before {
+      position: absolute;
+      top: 0;
+      bottom: 0;
+      left: 0;
+      width: 2px;
+      content: '';
+      background-color: var(--color-yattho-border-active);
+    }
+
+.menu-item .octicon {
+    width: 16px;
+    margin-right: var(--yattho-control-medium-gap, 8px);
+    color: var(--color-fg-muted);
+    text-align: center;
+  }
+
+.menu-item .Counter {
+    float: right;
+    margin-left: var(--yattho-control-small-gap, 4px);
+  }
+
+.menu-item .menu-warning {
+    float: right;
+    color: var(--color-attention-fg);
+  }
+
+.menu-item .avatar {
+    float: left;
+    margin-right: var(--yattho-control-small-gap, 4px);
+  }
+
+.menu-item.alert .Counter {
+      color: var(--color-danger-fg);
+    }
+
+.menu-heading {
+  display: block;
+  padding: var(--yattho-control-medium-paddingInline-condensed, 8px) var(--yattho-control-medium-paddingInline-spacious, 16px);
+  margin-top: 0;
+  margin-bottom: 0;
+  font-size: inherit;
+  font-weight: var(--base-text-weight-semibold, 600);
+  color: var(--color-fg-default);
+  border-bottom: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-muted);
+}
+
+.menu-heading:hover {
+    text-decoration: none;
+  }
+
+.menu-heading:first-child {
+    border-top-left-radius: var(--yattho-borderRadius-medium, 6px);
+    border-top-right-radius: var(--yattho-borderRadius-medium, 6px);
+  }
+
+.menu-heading:last-child {
+    border-bottom: 0;
+    border-bottom-right-radius: var(--yattho-borderRadius-medium, 6px);
+    border-bottom-left-radius: var(--yattho-borderRadius-medium, 6px);
+  }

data/app/components/yattho/alpha/menu.css.json

@@ -0,0 +1 @@
+{"name":"alpha/menu","selectors":[".menu",".menu-item",".menu-item:first-child",".menu-item:first-child::before",".menu-item:last-child",".menu-item:last-child::before",".menu-item:hover",".menu-item:active",".menu-item.selected","\n  .menu-item[aria-selected='true']","\n  .menu-item[aria-current]:not([aria-current='false'])",".menu-item.selected::before"," .menu-item[aria-selected='true']::before"," .menu-item[aria-current]:not([aria-current='false'])::before",".menu-item .octicon",".menu-item .Counter",".menu-item .menu-warning",".menu-item .avatar",".menu-item.alert .Counter",".menu-heading",".menu-heading:hover",".menu-heading:first-child",".menu-heading:last-child"]}

data/app/components/yattho/alpha/menu.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["menu.pcss"],"names":[],"mappings":"AAAA,SAAS;;AAET,+EAA+E;;AAE/E;EACE,mDAAmD;EACnD,gBAAgB;EAChB,6CAA6C;EAC7C,6EAA6E;EAC7E,qDAAqD;AACvD;;AAEA;EACE,kBAAkB;EAClB,cAAc;EACd,4HAA4H;EAC5H,8BAA8B;EAC9B,kFAAkF;AA2EpF;;AAzEE;IACE,aAAa;IACb,8DAA8D;IAC9D,+DAA+D;EAKjE;;AAHE;MACE,8DAA8D;IAChE;;AAGF;IACE,gBAAgB;IAChB,kEAAkE;IAClE,iEAAiE;EAKnE;;AAHE;MACE,iEAAiE;IACnE;;AAGF;IACE,qBAAqB;IACrB,6CAA6C;EAC/C;;AAEA;IACE,4CAA4C;EAC9C;;AAEA;;;IAGE,eAAe;IACf,6CAA6C;EAW/C;;AATE;MACE,kBAAkB;MAClB,MAAM;MACN,SAAS;MACT,OAAO;MACP,UAAU;MACV,WAAW;MACX,mDAAmD;IACrD;;AAGF;IACE,WAAW;IACX,mDAAmD;IACnD,4BAA4B;IAC5B,kBAAkB;EACpB;;AAEA;IACE,YAAY;IACZ,iDAAiD;EACnD;;AAEA;IACE,YAAY;IACZ,gCAAgC;EAClC;;AAEA;IACE,WAAW;IACX,kDAAkD;EACpD;;AAGE;MACE,6BAA6B;IAC/B;;AAIJ;EACE,cAAc;EACd,4HAA4H;EAC5H,aAAa;EACb,gBAAgB;EAChB,kBAAkB;EAClB,kDAAkD;EAClD,8BAA8B;EAC9B,kFAAkF;AAgBpF;;AAdE;IACE,qBAAqB;EACvB;;AAEA;IACE,8DAA8D;IAC9D,+DAA+D;EACjE;;AAEA;IACE,gBAAgB;IAChB,kEAAkE;IAClE,iEAAiE;EACnE","file":"menu.css","sourcesContent":["/* menu */\n\n/* A menu on the side of a page, defaults to left side. e.g. github.com/about */\n\n.menu {\n  margin-bottom: var(--yattho-stack-gap-normal, 16px);\n  list-style: none;\n  background-color: var(--color-canvas-default);\n  border: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-default);\n  border-radius: var(--yattho-borderRadius-medium, 6px);\n}\n\n.menu-item {\n  position: relative;\n  display: block;\n  padding: var(--yattho-control-medium-paddingInline-condensed, 8px) var(--yattho-control-medium-paddingInline-spacious, 16px);\n  color: var(--color-fg-default);\n  border-bottom: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-muted);\n\n  &:first-child {\n    border-top: 0;\n    border-top-left-radius: var(--yattho-borderRadius-medium, 6px);\n    border-top-right-radius: var(--yattho-borderRadius-medium, 6px);\n\n    &::before {\n      border-top-left-radius: var(--yattho-borderRadius-medium, 6px);\n    }\n  }\n\n  &:last-child {\n    border-bottom: 0;\n    border-bottom-right-radius: var(--yattho-borderRadius-medium, 6px);\n    border-bottom-left-radius: var(--yattho-borderRadius-medium, 6px);\n\n    &::before {\n      border-bottom-left-radius: var(--yattho-borderRadius-medium, 6px);\n    }\n  }\n\n  &:hover {\n    text-decoration: none;\n    background-color: var(--color-neutral-subtle);\n  }\n\n  &:active {\n    background-color: var(--color-canvas-subtle);\n  }\n\n  &.selected,\n  &[aria-selected='true'],\n  &[aria-current]:not([aria-current='false']) {\n    cursor: default;\n    background-color: var(--color-menu-bg-active);\n\n    &::before {\n      position: absolute;\n      top: 0;\n      bottom: 0;\n      left: 0;\n      width: 2px;\n      content: '';\n      background-color: var(--color-yattho-border-active);\n    }\n  }\n\n  & .octicon {\n    width: 16px;\n    margin-right: var(--yattho-control-medium-gap, 8px);\n    color: var(--color-fg-muted);\n    text-align: center;\n  }\n\n  & .Counter {\n    float: right;\n    margin-left: var(--yattho-control-small-gap, 4px);\n  }\n\n  & .menu-warning {\n    float: right;\n    color: var(--color-attention-fg);\n  }\n\n  & .avatar {\n    float: left;\n    margin-right: var(--yattho-control-small-gap, 4px);\n  }\n\n  &.alert {\n    & .Counter {\n      color: var(--color-danger-fg);\n    }\n  }\n}\n\n.menu-heading {\n  display: block;\n  padding: var(--yattho-control-medium-paddingInline-condensed, 8px) var(--yattho-control-medium-paddingInline-spacious, 16px);\n  margin-top: 0;\n  margin-bottom: 0;\n  font-size: inherit;\n  font-weight: var(--base-text-weight-semibold, 600);\n  color: var(--color-fg-default);\n  border-bottom: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-muted);\n\n  &:hover {\n    text-decoration: none;\n  }\n\n  &:first-child {\n    border-top-left-radius: var(--yattho-borderRadius-medium, 6px);\n    border-top-right-radius: var(--yattho-borderRadius-medium, 6px);\n  }\n\n  &:last-child {\n    border-bottom: 0;\n    border-bottom-right-radius: var(--yattho-borderRadius-medium, 6px);\n    border-bottom-left-radius: var(--yattho-borderRadius-medium, 6px);\n  }\n}"]}

data/app/components/yattho/alpha/menu.html.erb

@@ -0,0 +1,6 @@
+<%= render(Yattho::BaseComponent.new(**@system_arguments)) do %>
+  <%= heading %>
+  <% items.each do |item| %>
+    <%= item %>
+  <% end %>
+<% end %>

data/app/components/yattho/alpha/menu.pcss

@@ -0,0 +1,119 @@
+/* menu */
+
+/* A menu on the side of a page, defaults to left side. e.g. github.com/about */
+
+.menu {
+  margin-bottom: var(--yattho-stack-gap-normal, 16px);
+  list-style: none;
+  background-color: var(--color-canvas-default);
+  border: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-default);
+  border-radius: var(--yattho-borderRadius-medium, 6px);
+}
+
+.menu-item {
+  position: relative;
+  display: block;
+  padding: var(--yattho-control-medium-paddingInline-condensed, 8px) var(--yattho-control-medium-paddingInline-spacious, 16px);
+  color: var(--color-fg-default);
+  border-bottom: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-muted);
+
+  &:first-child {
+    border-top: 0;
+    border-top-left-radius: var(--yattho-borderRadius-medium, 6px);
+    border-top-right-radius: var(--yattho-borderRadius-medium, 6px);
+
+    &::before {
+      border-top-left-radius: var(--yattho-borderRadius-medium, 6px);
+    }
+  }
+
+  &:last-child {
+    border-bottom: 0;
+    border-bottom-right-radius: var(--yattho-borderRadius-medium, 6px);
+    border-bottom-left-radius: var(--yattho-borderRadius-medium, 6px);
+
+    &::before {
+      border-bottom-left-radius: var(--yattho-borderRadius-medium, 6px);
+    }
+  }
+
+  &:hover {
+    text-decoration: none;
+    background-color: var(--color-neutral-subtle);
+  }
+
+  &:active {
+    background-color: var(--color-canvas-subtle);
+  }
+
+  &.selected,
+  &[aria-selected='true'],
+  &[aria-current]:not([aria-current='false']) {
+    cursor: default;
+    background-color: var(--color-menu-bg-active);
+
+    &::before {
+      position: absolute;
+      top: 0;
+      bottom: 0;
+      left: 0;
+      width: 2px;
+      content: '';
+      background-color: var(--color-yattho-border-active);
+    }
+  }
+
+  & .octicon {
+    width: 16px;
+    margin-right: var(--yattho-control-medium-gap, 8px);
+    color: var(--color-fg-muted);
+    text-align: center;
+  }
+
+  & .Counter {
+    float: right;
+    margin-left: var(--yattho-control-small-gap, 4px);
+  }
+
+  & .menu-warning {
+    float: right;
+    color: var(--color-attention-fg);
+  }
+
+  & .avatar {
+    float: left;
+    margin-right: var(--yattho-control-small-gap, 4px);
+  }
+
+  &.alert {
+    & .Counter {
+      color: var(--color-danger-fg);
+    }
+  }
+}
+
+.menu-heading {
+  display: block;
+  padding: var(--yattho-control-medium-paddingInline-condensed, 8px) var(--yattho-control-medium-paddingInline-spacious, 16px);
+  margin-top: 0;
+  margin-bottom: 0;
+  font-size: inherit;
+  font-weight: var(--base-text-weight-semibold, 600);
+  color: var(--color-fg-default);
+  border-bottom: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-muted);
+
+  &:hover {
+    text-decoration: none;
+  }
+
+  &:first-child {
+    border-top-left-radius: var(--yattho-borderRadius-medium, 6px);
+    border-top-right-radius: var(--yattho-borderRadius-medium, 6px);
+  }
+
+  &:last-child {
+    border-bottom: 0;
+    border-bottom-right-radius: var(--yattho-borderRadius-medium, 6px);
+    border-bottom-left-radius: var(--yattho-borderRadius-medium, 6px);
+  }
+}

data/app/components/yattho/alpha/menu.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Yattho
+  module Alpha
+    # Use `Menu` to create vertical lists of navigational links.
+    class Menu < Yattho::Component
+      HEADING_TAG_OPTIONS = [:h1, :h2, :h3, :h4, :h5, :h6].freeze
+      HEADING_TAG_FALLBACK = :h2
+
+      # Optional menu heading
+      #
+      # @param tag [Symbol] <%= one_of(Yattho::Alpha::Menu::HEADING_TAG_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :heading, lambda { |tag:, **system_arguments|
+        system_arguments[:tag] = fetch_or_fallback(HEADING_TAG_OPTIONS, tag, HEADING_TAG_FALLBACK)
+        system_arguments[:classes] = class_names(
+          "menu-heading",
+          system_arguments[:classes]
+        )
+
+        Yattho::BaseComponent.new(**system_arguments)
+      }
+
+      # Required list of navigational links
+      #
+      # @param href [String] URL to be used for the Link
+      # @param selected [Boolean] Whether the item is the current selection
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_many :items, lambda { |href:, selected: false, **system_arguments|
+        deny_tag_argument(**system_arguments)
+        system_arguments[:tag] = :a
+        system_arguments[:href] = href
+        system_arguments[:'aria-current'] = :page if selected
+        system_arguments[:classes] = class_names(
+          "menu-item",
+          system_arguments[:classes]
+        )
+
+        Yattho::BaseComponent.new(**system_arguments)
+      }
+
+      # @example Default
+      #   <%= render(Yattho::Alpha::Menu.new) do |component| %>
+      #     <% component.with_heading(tag: :h2) do %>
+      #       Heading
+      #     <% end %>
+      #     <% component.with_item(selected: true, href: "#url") do %>
+      #       Item 1
+      #     <% end %>
+      #     <% component.with_item(href: "#url") do %>
+      #       <%= render(Yattho::Beta::Octicon.new("check")) %>
+      #       With Icon
+      #     <% end %>
+      #     <% component.with_item(href: "#url") do %>
+      #       <%= render(Yattho::Beta::Octicon.new("check")) %>
+      #       With Icon and Counter
+      #       <%= render(Yattho::Beta::Counter.new(count: 25)) %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(**system_arguments)
+        @system_arguments = deny_tag_argument(**system_arguments)
+        @system_arguments[:tag] = :nav
+        @system_arguments[:classes] = class_names(
+          "menu",
+          @system_arguments[:classes]
+        )
+      end
+
+      def render?
+        items.any?
+      end
+    end
+  end
+end

data/app/components/yattho/alpha/modal_dialog.d.ts

@@ -0,0 +1,18 @@
+export declare class ModalDialogElement extends HTMLElement {
+    #private;
+    openButton: HTMLButtonElement | null;
+    get open(): boolean;
+    set open(value: boolean);
+    get showButtons(): NodeList;
+    connectedCallback(): void;
+    show(): void;
+    close(closedNotCancelled?: boolean): void;
+}
+declare global {
+    interface Window {
+        ModalDialogElement: typeof ModalDialogElement;
+    }
+    interface HTMLElementTagNameMap {
+        'modal-dialog': ModalDialogElement;
+    }
+}