Deprecated Primer::LocalTime in favor of `Primer::Beta::RelativeTim…

…e` (#1687) Co-authored-by: Jon Rohan <[email protected]> Co-authored-by: Keith Cirkel <[email protected]>
primer · Dec 8, 2022 · a5b6f02 · a5b6f02
1 parent 988077a
commit a5b6f02
Show file tree

Hide file tree

Showing 10 changed files with 111 additions and 8 deletions.
diff --git a/.changeset/long-ears-sniff.md b/.changeset/long-ears-sniff.md
@@ -0,0 +1,5 @@
+---
+'@primer/view-components': patch
+---
+
+Deprecate Primer::LocalTime in favor of Primer::RelativeTime
diff --git a/app/components/primer/beta/relative_time.rb b/app/components/primer/beta/relative_time.rb
@@ -101,7 +101,7 @@ class RelativeTime < Primer::Component
       # @param month [Symbol] What format months should take. <%= one_of(Primer::Beta::RelativeTime::MONTH_OPTIONS) %>
       # @param year [Symbol] What format years should take. <%= one_of(Primer::Beta::RelativeTime::YEAR_OPTIONS) %>
       # @param time_zone_name [Symbol] What format the time zone should take. <%= one_of(Primer::Beta::RelativeTime::TIMEZONENAME_OPTIONS) %>
-      # @param threshold [string] The threshold at which relative time displays become absolute.
+      # @param threshold [string] The threshold, in ISO-8601 'durations' format, at which relative time displays become absolute.
       # @param precision [Symbol] The precision elapsed time should display. <%= one_of(Primer::Beta::RelativeTime::PRECISION_OPTIONS) %>
       # @param format [Symbol] The format the display should take. <%= one_of(Primer::Beta::RelativeTime::FORMAT_OPTIONS) %>
       # @param lang [string] The language to use.

diff --git a/app/components/primer/local_time.rb b/app/components/primer/local_time.rb
@@ -3,6 +3,8 @@
 module Primer
   # Use `LocalTime` to format a date and time in the user's preferred locale format. This component requires JavaScript.
   class LocalTime < Primer::Component
+    status :deprecated
+
     DEFAULT_DIGIT_TYPE = :numeric
     DIGIT_TYPE_OPTIONS = [DEFAULT_DIGIT_TYPE, :"2-digit"].freeze
 

diff --git a/component_status_migrator.thor b/component_status_migrator.thor
@@ -38,6 +38,14 @@ class ComponentStatusMigrator < Thor::Group
     move_file("template", template_path, template_path_with_status)
   end
 
+  def move_reamining_files
+    Dir["app/components/primer/#{name.underscore}.*"].each do |file_path|
+      file_name = File.basename(file_path)
+      new_path = "#{status_full_path}#{file_name}"
+      move_file("misc", file_path, new_path)
+    end
+  end
+
   def move_test
     move_file("test", test_path, test_path_with_status)
   end
@@ -69,7 +77,11 @@ class ComponentStatusMigrator < Thor::Group
   end
 
   def remove_suffix_from_preview_class
-    if name == name_without_suffix
+    if preview_path.include?("_component") && !name.include?("Component") # rubocop:disable Rails/NegateInclude
+      # if the class name does not include 'Component', but the file name does include '_component',
+      # this line will correct it by removing the incosistency with the word 'Component'
+      gsub_file(preview_path_with_status, "class #{name}Component", "class #{name_without_suffix}")
+    elsif name == name_without_suffix
       puts "No change needed - component suffix not removed from lookbook preview class name"
     else
       gsub_file(preview_path_with_status, "class #{name}", "class #{name_without_suffix}")
@@ -90,6 +102,13 @@ class ComponentStatusMigrator < Thor::Group
     gsub_file(nav_file, "url: \"/components/#{name_without_suffix.downcase}\"", "url: \"/components/#{status_url}#{name_without_suffix.downcase}\"")
   end
 
+  def update_primer_js_imports
+    primer_js = "app/components/primer/primer.ts"
+    original_content = "import './#{name.underscore}'"
+    updated_content = "import './#{status_folder_name}#{name_without_suffix.underscore}'"
+    gsub_file(primer_js, original_content, updated_content)
+  end
+
   def update_all_references
     exclude_files = [
       ".overmind.sock",
@@ -202,7 +221,11 @@ class ComponentStatusMigrator < Thor::Group
   end
 
   def preview_path
-    @preview_path ||= "previews/primer/#{name.underscore}_preview.rb"
+    @preview_path ||= begin
+      path = "previews/primer/#{name.underscore}_preview.rb"
+      path_with_component = "previews/primer/#{name.underscore}_component_preview.rb"
+      File.exist?(path_with_component) ? path_with_component : path
+    end
   end
 
   def preview_path_with_status
@@ -221,6 +244,10 @@ class ComponentStatusMigrator < Thor::Group
     @status_module ||= "#{class_status}::" unless stable?
   end
 
+  def status_full_path
+    @status_full_path ||= "app/components/primer/#{status_folder_name}"
+  end
+
   def template_path
     @template_path ||= "app/components/primer/#{name.underscore}.html.erb"
   end

diff --git a/docs/content/guides/primer_local_time.md b/docs/content/guides/primer_local_time.md
@@ -0,0 +1,63 @@
+---
+title: Moving Away From `Primer::LocalTime`
+---
+
+This guide will show you how to upgrade from the now deprecated
+[`Primer::LocalTime`](https://primer.style/view-components/components/localtime)
+to the latest [`Primer::Beta::RelativeTime`](https://primer.style/view-components/components/beta/relativetime)
+component.
+
+## A Migration Example
+
+The most common use case of the `LocalTime` component can be migrated with only
+a few minor changes.
+
+For example, if the `LocalTime` was set up in this way:
+
+```rb
+<%= Primer::LocalTime(datetime: Time.now, initial_text: Time.now.iso8601) %>
+```
+
+It can be migrated by removing `initial_text`c, setting an empty `prefix`, and adding `threshold: "PT0S"`.
+
+```rb
+<%= Primer::Beta::RelativeTime(datetime: Time.now, prefix: "", threshold: "PT0S") %>
+```
+
+The `RelativeTime` component defaults to the `iso8601` format and does not need
+to be specified directly.
+
+The `threshold` value is an [ISO-8601 "duration"](https://en.wikipedia.org/wiki/ISO_8601#Durations) that tells the `RelativeTime`
+component to display the absolute date/time, instead of relative time
+description. The example of `PT0S` says to switch to absolute time display
+starting zero (0) seconds ago. In practice, this means it will always display
+the absolute time. With the `LocalTime` component, `PT0S` was the default
+threshold. The `RelativeTime` component defaults to `P30D`, however, and
+it will need to be zeroed out to always display a datetime.
+
+## Arguments
+
+The following arguments are different between `LocalTime` and `RelativeTime`.
+
+| From `Primer::LocalTime` | To `Primer::Beta::RelativeTime` | Notes |
+|--------------------------|---------------------------------|-------|
+| `initial_text` | n/a         | No longer used.                                                                                                     |
+| n/a            | `tense`     | Which tense to use. One of `:auto`, `:future`, or `:past`.                                                          |
+| n/a            | `prefix`    | What to prefix the relative ime display with.                                                                       |
+| n/a            | `threshold` | The threshold, in ISO-8601 'durations' format, at which relative time displays become absolute.                                                      |
+| n/a            | `precision` | The precision elapsed time should display. One of nil, `:day`, `:hour`, `:minute`, `:month`, `:second`, or `:year`. |
+| n/a            | `format`    | The format the display should take. One of `:auto`, `:elapsed`, or `:micro`.                                        |
+| n/a            | `lang`      | The language to use.                                                                                                |
+| n/a            | `title`     | Provide a custom title to the element.                                                                              |
+
+The remaining arguments stayed the same.
+
+Please see the following documentation for complete descriptions and examples.
+
+* [Deprecated `Primer::LocalTime`](https://primer.style/view-components/components/localtime)
+* [`Primer::Beta::RelativeTime` component](https://primer.style/view-components/components/beta/relativetime)
+* [`Primer::Beta::RelativeTime` Lookbook examples](https://primer.style/view-components/lookbook/inspect/primer/beta/relativetime/default)
+
+<p>&nbsp;</p>
+
+[&larr; Back to migration guides](https://primer.style/view-components/migration)
diff --git a/docs/content/migration.md b/docs/content/migration.md
@@ -29,3 +29,4 @@ components.
 |----------------------|-----------------------|-------|
 | [`Primer::ButtonComponent`](https://primer.style/view-components/components/button) | [`Primer::Beta::Button`](https://primer.style/view-components/components/beta/button) | [Upgrade to Primer::Beta::Button](https://primer.style/view-components/guides/primer_button_component) |
 | [`Primer::DropdownMenuComponent`](https://primer.style/view-components/components/dropdownmenu) | [`Primer::Alpha::Dropdown`](https://primer.style/view-components/components/alpha/dropdown) | [Upgrade to Primer::Alpha::Dropdown](https://primer.style/view-components/guides/primer_dropdown_menu_component) |
+| [`Primer::LocalTime`](https://primer.style/view-components/components/localtime) | [`Primer::Beta::RelativeTime`](https://primer.style/view-components/components/beta/relativetime) | [Upgrade to Primer::Beta::RelativeTime](https://primer.style/view-components/guides/primer_local_time) |
diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml
@@ -69,8 +69,6 @@
     url: "/components/alpha/layout"
   - title: Link
     url: "/components/beta/link"
-  - title: LocalTime
-    url: "/components/localtime"
   - title: Markdown
     url: "/components/beta/markdown"
   - title: Menu
@@ -131,6 +129,8 @@
     url: "/components/dropdownmenu"
   - title: IconButton
     url: "/components/iconbutton"
+  - title: LocalTime
+    url: "/components/localtime"
   - title: Tooltip
     url: "/components/tooltip"
 - title: Architecture decisions

diff --git a/lib/primer/deprecations.yml b/lib/primer/deprecations.yml
@@ -55,6 +55,11 @@ deprecations:
     autocorrect: true
     replacement: "Primer::Beta::Label"
 
+  - component: "Primer::LocalTime"
+    autocorrect: false
+    replacement: "Primer::Beta::RelativeTime"
+    guide: "https://primer.style/view-components/guides/primer_local_time"
+
   - component: "Primer::LinkComponent"
     autocorrect: true
     replacement: "Primer::Beta::Link"

diff --git a/static/arguments.json b/static/arguments.json
@@ -1885,7 +1885,7 @@
         "name": "threshold",
         "type": "string",
         "default": "`nil`",
-        "description": "The threshold at which relative time displays become absolute."
+        "description": "The threshold, in ISO-8601 'durations' format, at which relative time displays become absolute."
       },
       {
         "name": "precision",
@@ -2177,7 +2177,7 @@
   },
   {
     "component": "LocalTime",
-    "status": "alpha",
+    "status": "deprecated",
     "source": "https://github.com/primer/view_components/tree/main/app/components/primer/local_time.rb",
     "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/local_time/default/",
     "parameters": [

diff --git a/static/statuses.json b/static/statuses.json
@@ -78,7 +78,7 @@
   "Primer::LabelComponent": "deprecated",
   "Primer::LayoutComponent": "alpha",
   "Primer::LinkComponent": "deprecated",
-  "Primer::LocalTime": "alpha",
+  "Primer::LocalTime": "deprecated",
   "Primer::Markdown": "deprecated",
   "Primer::MenuComponent": "deprecated",
   "Primer::Navigation::TabComponent": "alpha",