primer_view_components 0.0.96 → 0.0.97

data/app/components/primer/alpha/nav_list.js

@@ -0,0 +1,130 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/* eslint-disable custom-elements/expose-class-on-global */
+import { controller, target, targets } from '@github/catalyst';
+let NavListElement = class NavListElement extends HTMLElement {
+    connectedCallback() {
+        this.setShowMoreItemState();
+    }
+    get showMoreDisabled() {
+        return this.showMoreItem.hasAttribute('aria-disabled');
+    }
+    set showMoreDisabled(value) {
+        if (value) {
+            this.showMoreItem.setAttribute('aria-disabled', 'true');
+        }
+        else {
+            this.showMoreItem.removeAttribute('aria-disabled');
+        }
+        this.showMoreItem.classList.toggle('disabled', value);
+    }
+    set currentPage(value) {
+        this.showMoreItem.setAttribute('data-current-page', value.toString());
+    }
+    get currentPage() {
+        return parseInt(this.showMoreItem.getAttribute('data-current-page')) || 1;
+    }
+    get totalPages() {
+        return parseInt(this.showMoreItem.getAttribute('data-total-pages')) || 1;
+    }
+    get paginationSrc() {
+        return this.showMoreItem.getAttribute('src') || '';
+    }
+    // expand collapsible item onClick
+    expandItem(item) {
+        var _a;
+        (_a = item.nextElementSibling) === null || _a === void 0 ? void 0 : _a.removeAttribute('data-hidden');
+        item.setAttribute('aria-expanded', 'true');
+    }
+    collapseItem(item) {
+        var _a;
+        (_a = item.nextElementSibling) === null || _a === void 0 ? void 0 : _a.setAttribute('data-hidden', '');
+        item.setAttribute('aria-expanded', 'false');
+    }
+    itemIsExpanded(item) {
+        if ((item === null || item === void 0 ? void 0 : item.tagName) === 'A') {
+            return true;
+        }
+        return (item === null || item === void 0 ? void 0 : item.getAttribute('aria-expanded')) === 'true';
+    }
+    // expand/collapse item
+    handleItemWithSubItemClick(e) {
+        const target = e.target;
+        if (!(target instanceof HTMLElement))
+            return;
+        const button = target.closest('button');
+        if (!button)
+            return;
+        if (this.itemIsExpanded(button)) {
+            this.collapseItem(button);
+        }
+        else {
+            this.expandItem(button);
+        }
+        e.stopPropagation();
+    }
+    async showMore(e) {
+        var _a, _b;
+        e.preventDefault();
+        if (this.showMoreDisabled)
+            return;
+        this.showMoreDisabled = true;
+        let html;
+        try {
+            const paginationURL = new URL(this.paginationSrc, window.location.origin);
+            this.currentPage++;
+            paginationURL.searchParams.append('page', this.currentPage.toString());
+            const response = await fetch(paginationURL);
+            if (!response.ok)
+                return;
+            html = await response.text();
+            if (this.currentPage === this.totalPages) {
+                this.showMoreItem.hidden = true;
+            }
+        }
+        catch (err) {
+            // Ignore network errors
+            this.showMoreDisabled = false;
+            this.currentPage--;
+            return;
+        }
+        const fragment = this.parseHTML(document, html);
+        (_a = fragment === null || fragment === void 0 ? void 0 : fragment.querySelector('li > a')) === null || _a === void 0 ? void 0 : _a.setAttribute('data-targets', 'nav-list.focusMarkers');
+        this.list.insertBefore(fragment, this.showMoreItem);
+        (_b = this.focusMarkers.pop()) === null || _b === void 0 ? void 0 : _b.focus();
+        this.showMoreDisabled = false;
+    }
+    setShowMoreItemState() {
+        if (!this.showMoreItem) {
+            return;
+        }
+        if (this.currentPage < this.totalPages) {
+            this.showMoreItem.hidden = false;
+        }
+        else {
+            this.showMoreItem.hidden = true;
+        }
+    }
+    parseHTML(document, html) {
+        const template = document.createElement('template');
+        // eslint-disable-next-line github/no-inner-html
+        template.innerHTML = html;
+        return document.importNode(template.content, true);
+    }
+};
+__decorate([
+    target
+], NavListElement.prototype, "list", void 0);
+__decorate([
+    target
+], NavListElement.prototype, "showMoreItem", void 0);
+__decorate([
+    targets
+], NavListElement.prototype, "focusMarkers", void 0);
+NavListElement = __decorate([
+    controller
+], NavListElement);

data/app/components/primer/alpha/nav_list.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    # `NavList` provides a simple way to render side navigation, i.e. navigation
+    # that appears to the left or right side of some main content. Each section in a
+    # nav list is a list of links.
+    #
+    # Nav list sections can contain sub items. Rather than navigating to a URL, sections
+    # with sub items expand and collapse on click. To indicate this functionality, the
+    # section will automatically render with a trailing chevron icon that changes direction
+    # when the section expands and collapses.
+    #
+    # Nav list items appear visually active when selected. Each nav item must have one
+    # or more ID values that determine which item will appear selected. Use the
+    # `selected_item_id` argument to select the appropriate item.
+    class NavList < Primer::Component
+      status :alpha
+
+      # Sections. Each section is a list of links and an optional heading.
+      #
+      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::NavList::Section) %>.
+      renders_many :sections, lambda { |**system_arguments|
+        Primer::Alpha::NavList::Section.new(selected_item_id: @selected_item_id, **system_arguments)
+      }
+
+      # @example Items and headings
+      #
+      #   <%= render(Primer::Alpha::NavList.new(selected_item_id: :personal_info)) do |component| %>
+      #     <% component.with_section(aria: { label: "Settings" }) do |section| %>
+      #       <% section.with_item(label: "General", selected_by_ids: :general, href: "/settings/general") %>
+      #     <% end %>
+      #     <% component.with_section(aria: { label: "Account settings" }) do |section| %>
+      #       <% section.with_heading(title: "Account Settings") %>
+      #       <% section.with_item(label: "Personal Information", selected_by_ids: :personal_info, href: "/account/info") %>
+      #       <% section.with_item(label: "Password", selected_by_ids: :password, href: "/account/password") %>
+      #       <% section.with_item(label: "Billing info", selected_by_ids: :billing, href: "/account/billing") %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # @example Leading and trailing visuals
+      #
+      #   <%= render(Primer::Alpha::NavList.new(selected_item_id: :personal_info)) do |component| %>
+      #     <% component.with_section(aria: { label: "Account settings" }) do |section| %>
+      #       <% section.with_heading(title: "Account Settings") %>
+      #       <% section.with_item(label: "Personal Information", selected_by_ids: :personal_info, href: "/account/info") do |item| %>
+      #         <% item.with_leading_visual_avatar(src: "https://github.com/github.png", alt: "GitHub") %>
+      #       <% end %>
+      #       <% section.with_item(label: "Notifications", selected_by_ids: :notifications, href: "/account/notifications") do |item| %>
+      #         <% item.with_leading_visual_icon(icon: :bell) %>
+      #         <% item.with_trailing_visual_counter(count: 15) %>
+      #       <% end %>
+      #       <% section.with_item(label: "Billing info", selected_by_ids: :billing, href: "/account/billing") do |item| %>
+      #         <% item.with_leading_visual_icon(icon: :package) %>
+      #         <% item.with_trailing_visual_icon(icon: :"dot-fill", color: :attention) %>
+      #       <% end %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # @example Expandable sub items
+      #
+      #   <%= render(Primer::Alpha::NavList.new(selected_item_id: :email_notifications)) do |component| %>
+      #     <% component.with_section(aria: { label: "Account settings" }) do |section| %>
+      #       <% section.with_heading(title: "Account Settings") %>
+      #       <% section.with_item(label: "Notification settings", selected_by_ids: :notifications) do |item| %>
+      #         <% item.with_leading_visual_icon(icon: :bell) %>
+      #         <% item.with_item(label: "Email", selected_by_ids: :email_notifications, href: "/account/notifications/email") do |subitem| %>
+      #           <% subitem.with_trailing_visual_icon(icon: :mail) %>
+      #         <% end %>
+      #         <% item.with_item(label: "SMS", selected_by_ids: :sms_notifications, href: "/account/notifications/sms") do |subitem| %>
+      #           <% subitem.with_trailing_visual_icon(icon: :"device-mobile") %>
+      #         <% end %>
+      #       <% end %>
+      #       <% section.with_item(label: "Messages", selected_by_ids: :messages) do |item| %>
+      #         <% item.with_leading_visual_icon(icon: :bookmark) %>
+      #         <% item.with_item(label: "Inbox", href: "/account/messages/inbox") do |subitem| %>
+      #           <% subitem.with_trailing_visual_counter(count: 10) %>
+      #         <% end %>
+      #         <% item.with_item(label: "Organizer", href: "/account/messages/organizer") do |subitem| %>
+      #           <% subitem.with_trailing_visual_label(scheme: :primary) { "New" } %>
+      #         <% end %>
+      #       <% end %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # @example Trailing action
+      #
+      #   <%= render(Primer::Alpha::NavList.new) do |component| %>
+      #     <% component.with_section(aria: { label: "Favorite foods" }) do |section| %>
+      #       <% section.with_heading(title: "My Favorite Foods") %>
+      #       <% section.with_item(label: "Popplers", selected_by_ids: :popplers, href: "/foods/popplers") do |item| %>
+      #         <% item.with_trailing_action(show_on_hover: false, icon: "plus", "aria-label": "Add new food", size: :medium) %>
+      #       <% end %>
+      #       <% section.with_item(label: "Slurm", selected_by_ids: :slurm, href: "/foods/slurm") do |item| %>
+      #         <% item.with_trailing_action(show_on_hover: true, icon: "plus", "aria-label": "Add new food", size: :medium) %>
+      #       <% end %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # @param selected_item_id [Symbol] The ID of the currently selected item. The default is `nil`, meaning no item is selected.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(selected_item_id: nil, **system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:classes] = class_names(
+          @system_arguments[:classes],
+          "ActionListWrap"
+        )
+        @selected_item_id = selected_item_id
+      end
+    end
+  end
+end

data/app/components/primer/alpha/nav_list.ts

@@ -0,0 +1,129 @@
+/* eslint-disable custom-elements/expose-class-on-global */
+import {controller, target, targets} from '@github/catalyst'
+
+@controller
+class NavListElement extends HTMLElement {
+  @target list: HTMLElement
+  @target showMoreItem: HTMLElement
+  @targets focusMarkers: HTMLElement[]
+
+  connectedCallback(): void {
+    this.setShowMoreItemState()
+  }
+
+  get showMoreDisabled(): boolean {
+    return this.showMoreItem.hasAttribute('aria-disabled')
+  }
+
+  set showMoreDisabled(value: boolean) {
+    if (value) {
+      this.showMoreItem.setAttribute('aria-disabled', 'true')
+    } else {
+      this.showMoreItem.removeAttribute('aria-disabled')
+    }
+    this.showMoreItem.classList.toggle('disabled', value)
+  }
+
+  set currentPage(value: number) {
+    this.showMoreItem.setAttribute('data-current-page', value.toString())
+  }
+
+  get currentPage(): number {
+    return parseInt(this.showMoreItem.getAttribute('data-current-page') as string) || 1
+  }
+
+  get totalPages(): number {
+    return parseInt(this.showMoreItem.getAttribute('data-total-pages') as string) || 1
+  }
+
+  get paginationSrc(): string {
+    return this.showMoreItem.getAttribute('src') || ''
+  }
+
+  // expand collapsible item onClick
+  expandItem(item: HTMLElement) {
+    item.nextElementSibling?.removeAttribute('data-hidden')
+    item.setAttribute('aria-expanded', 'true')
+  }
+
+  collapseItem(item: HTMLElement) {
+    item.nextElementSibling?.setAttribute('data-hidden', '')
+    item.setAttribute('aria-expanded', 'false')
+  }
+
+  itemIsExpanded(item: HTMLElement | null) {
+    if (item?.tagName === 'A') {
+      return true
+    }
+    return item?.getAttribute('aria-expanded') === 'true'
+  }
+
+  // expand/collapse item
+  handleItemWithSubItemClick(e: Event) {
+    const target = e.target
+    if (!(target instanceof HTMLElement)) return
+
+    const button = target.closest<HTMLButtonElement>('button')
+    if (!button) return
+    if (this.itemIsExpanded(button)) {
+      this.collapseItem(button)
+    } else {
+      this.expandItem(button)
+    }
+
+    e.stopPropagation()
+  }
+
+  private async showMore(e: Event) {
+    e.preventDefault()
+    if (this.showMoreDisabled) return
+    this.showMoreDisabled = true
+    let html
+    try {
+      const paginationURL = new URL(this.paginationSrc, window.location.origin)
+      this.currentPage++
+      paginationURL.searchParams.append('page', this.currentPage.toString())
+      const response = await fetch(paginationURL)
+      if (!response.ok) return
+      html = await response.text()
+      if (this.currentPage === this.totalPages) {
+        this.showMoreItem.hidden = true
+      }
+    } catch (err) {
+      // Ignore network errors
+      this.showMoreDisabled = false
+      this.currentPage--
+      return
+    }
+    const fragment = this.parseHTML(document, html)
+    fragment?.querySelector('li > a')?.setAttribute('data-targets', 'nav-list.focusMarkers')
+    this.list.insertBefore(fragment, this.showMoreItem)
+    this.focusMarkers.pop()?.focus()
+    this.showMoreDisabled = false
+  }
+
+  private setShowMoreItemState() {
+    if (!this.showMoreItem) {
+      return
+    }
+
+    if (this.currentPage < this.totalPages) {
+      this.showMoreItem.hidden = false
+    } else {
+      this.showMoreItem.hidden = true
+    }
+  }
+
+  private parseHTML(document: Document, html: string): DocumentFragment {
+    const template = document.createElement('template')
+    // eslint-disable-next-line github/no-inner-html
+    template.innerHTML = html
+    return document.importNode(template.content, true)
+  }
+}
+
+declare global {
+  interface Window {
+    NavListElement: typeof NavListElement
+  }
+}

data/app/components/primer/primer.d.ts

@@ -1,4 +1,5 @@
 import './alpha/modal_dialog';
+import './alpha/nav_list';
 import './alpha/toggle_switch';
 import './alpha/tool_tip';
 import './beta/auto_complete/auto_complete';

data/app/components/primer/primer.js

@@ -1,4 +1,5 @@
 import './alpha/modal_dialog';
+import './alpha/nav_list';
 import './alpha/toggle_switch';
 import './alpha/tool_tip';
 import './beta/auto_complete/auto_complete';

data/app/components/primer/primer.pcss

@@ -1,2 +1,3 @@
 /* CSS component styles here */
 @import "./beta/button.pcss";
+@import "./alpha/action_list/action-list.pcss";

data/app/components/primer/primer.ts

@@ -1,4 +1,5 @@
 import './alpha/modal_dialog'
+import './alpha/nav_list'
 import './alpha/toggle_switch'
 import './alpha/tool_tip'
 import './beta/auto_complete/auto_complete'

data/lib/postcss_mixins/activeIndicatorLine.pcss

@@ -0,0 +1,11 @@
+/* active indicator line for navlist items */
+@define-mixin activeIndicatorLine $padding-left: calc(-1 * var(--base-size-8, 8px)) {
+  position: absolute;
+  top: calc(50% - 12px);
+  left: $padding-left;
+  width: var(--base-size-4, 4px);
+  height: var(--base-size-24, 24px);
+  content: '';
+  background: var(--color-accent-fg);
+  border-radius: var(--primer-borderRadius-medium, 6px);
+}

data/lib/primer/view_components/version.rb

@@ -5,7 +5,7 @@ module Primer
     module VERSION
       MAJOR = 0
       MINOR = 0
-      PATCH = 96
+      PATCH = 97
 
       STRING = [MAJOR, MINOR, PATCH].join(".")
     end

data/lib/tasks/docs.rake

@@ -88,7 +88,14 @@ namespace :docs do
       Primer::Alpha::TabNav,
       Primer::Alpha::TabPanels,
       Primer::Alpha::Tooltip,
-      Primer::Alpha::ToggleSwitch
+      Primer::Alpha::ToggleSwitch,
+      Primer::Alpha::ActionList,
+      Primer::Alpha::NavList,
+      Primer::Alpha::NavList::Item,
+      Primer::Alpha::NavList::Section,
+      Primer::Alpha::ActionList::Divider,
+      Primer::Alpha::ActionList::Heading,
+      Primer::Alpha::ActionList::Item
     ]
 
     js_components = [
@@ -104,7 +111,23 @@ namespace :docs do
       Primer::Alpha::Tooltip,
       Primer::ButtonComponent,
       Primer::IconButton,
-      Primer::LinkComponent
+      Primer::LinkComponent,
+      Primer::Alpha::ToggleSwitch,
+      Primer::Alpha::ActionList,
+      Primer::Alpha::NavList,
+      Primer::Alpha::NavList::Section
+    ]
+
+    components_without_examples = [
+      # ActionList is a base component that should not be used by itself
+      Primer::Alpha::ActionList,
+      Primer::Alpha::ActionList::Divider,
+      Primer::Alpha::ActionList::Heading,
+      Primer::Alpha::ActionList::Item,
+
+      # Examples can be seen in the NavList docs
+      Primer::Alpha::NavList::Item,
+      Primer::Alpha::NavList::Section
     ]
 
     all_components = Primer::Component.descendants - [Primer::BaseComponent]
@@ -212,7 +235,9 @@ namespace :docs do
         args_for_components << component_args
 
         # Slots V2 docs
-        slot_v2_methods = documentation.meths.select { |x| x[:renders_one] || x[:renders_many] }
+        slot_v2_methods = documentation.meths.select do |mtd|
+          (mtd[:renders_one] || mtd[:renders_many]) && mtd.tag(:private).nil?
+        end
 
         if slot_v2_methods.any?
           f.puts
@@ -220,7 +245,7 @@ namespace :docs do
 
           slot_v2_methods.each do |slot_documentation|
             f.puts
-            f.puts("### `#{slot_documentation.name.to_s.capitalize}`")
+            f.puts("### `#{slot_documentation.name}`")
 
             if slot_documentation.base_docstring.to_s.present?
               f.puts
@@ -240,26 +265,30 @@ namespace :docs do
           end
         end
 
-        errors << { component.name => { example: "No examples found" } } unless initialize_method.tags(:example).any?
-
-        f.puts
-        f.puts("## Examples")
+        example_tags = initialize_method.tags(:example)
 
-        initialize_method.tags(:example).each do |tag|
-          name, description, code = parse_example_tag(tag)
+        if example_tags.any?
           f.puts
-          f.puts("### #{name}")
-          if description
+          f.puts("## Examples")
+
+          example_tags.each do |tag|
+            name, description, code = parse_example_tag(tag)
+            f.puts
+            f.puts("### #{name}")
+            if description
+              f.puts
+              f.puts(view_context.render(inline: description.squish))
+            end
             f.puts
-            f.puts(view_context.render(inline: description.squish))
+            html = view_context.render(inline: code)
+            f.puts("<Example src=\"#{html.tr('"', "\'").delete("\n")}\" />")
+            f.puts
+            f.puts("```erb")
+            f.puts(code.to_s)
+            f.puts("```")
           end
-          f.puts
-          html = view_context.render(inline: code)
-          f.puts("<Example src=\"#{html.tr('"', "\'").delete("\n")}\" />")
-          f.puts
-          f.puts("```erb")
-          f.puts(code.to_s)
-          f.puts("```")
+        else
+          errors << { component.name => { example: "No examples found" } } unless components_without_examples.include?(component)
         end
       end
     end
@@ -454,12 +483,12 @@ namespace :docs do
   end
 
   def docs_metadata(component)
-    (status_module, short_name) = status_module_and_short_name(component)
+    status_module, short_name, class_name = status_module_and_short_name(component)
     status_path = status_module.nil? ? "" : "#{status_module}/"
     status = component.status.to_s
 
     {
-      title: short_name,
+      title: class_name,
       component_id: short_name.underscore,
       status: status.capitalize,
       source: source_url(component),

data/lib/yard/docs_helper.rb

@@ -44,10 +44,10 @@ module YARD
     end
 
     def link_to_component(component)
-      (status_module, short_name) = status_module_and_short_name(component)
+      status_module, short_name, class_name = status_module_and_short_name(component)
       status_path = status_module.nil? ? "" : "#{status_module}/"
 
-      "[#{short_name}](/components/#{status_path}#{short_name.downcase})"
+      "[#{class_name}](/components/#{status_path}#{short_name.downcase})"
     end
 
     def link_to_octicons
@@ -62,7 +62,7 @@ module YARD
       name_with_status = component.name.gsub(/Primer::|Component/, "")
 
       m = name_with_status.match(/(?<status>Beta|Alpha|Deprecated)?(?<_colons>::)?(?<name>.*)/)
-      [m[:status]&.downcase, m[:name].gsub("::", "")]
+      [m[:status]&.downcase, m[:name].gsub("::", ""), m[:name]]
     end
 
     def pretty_value(val)