diff --git a/.changeset/long-ears-sniff.md b/.changeset/long-ears-sniff.md new file mode 100644 index 0000000000..0620fce7d0 --- /dev/null +++ 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 index 6ba9a0bbdf..da49c7bb3f 100644 --- 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 index cb6c83d630..fe12bff174 100644 --- 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 index 6d853be71f..850632a3f0 100644 --- 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 new file mode 100644 index 0000000000..198602b6db --- /dev/null +++ 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) + +

 

+ +[← Back to migration guides](https://primer.style/view-components/migration) diff --git a/docs/content/migration.md b/docs/content/migration.md index 854a4e56bc..fd1a22cff7 100644 --- 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 index 1289c51f22..a5dff9ef44 100644 --- 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 index e980b9e56e..82957ae63c 100644 --- 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 index a2aee74a08..af7e42e06e 100644 --- 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 index e249670d92..c1dbc794ce 100644 --- 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",