From 864fb98fd38af79490b326caf3a0fe325ffb3066 Mon Sep 17 00:00:00 2001 From: "Harry R. Schwartz" Date: Mon, 13 Mar 2023 11:17:07 -0700 Subject: [PATCH] Deprecate `Primer::Truncate` in favor of `Primer::Beta::Truncate` (#1877) --- .changeset/chilled-phones-pump.md | 5 ++ app/components/primer/truncate.rb | 2 +- docs/content/guides/primer_local_time.md | 3 +- docs/content/guides/primer_time_ago.md | 4 +- docs/content/guides/primer_truncate.md | 67 +++++++++++++++++++ docs/content/migration.md | 1 + .../src/@primer/gatsby-theme-doctocat/nav.yml | 2 + lib/primer/deprecations.yml | 5 ++ static/arguments.json | 2 +- static/statuses.json | 2 +- 10 files changed, 87 insertions(+), 6 deletions(-) create mode 100644 .changeset/chilled-phones-pump.md create mode 100644 docs/content/guides/primer_truncate.md diff --git a/.changeset/chilled-phones-pump.md b/.changeset/chilled-phones-pump.md new file mode 100644 index 0000000000..b08ffb4338 --- /dev/null +++ b/.changeset/chilled-phones-pump.md @@ -0,0 +1,5 @@ +--- +'@primer/view-components': patch +--- + +Deprecate Primer::Truncate in favor of Primer::Beta::Truncate, and adding a migration guide diff --git a/app/components/primer/truncate.rb b/app/components/primer/truncate.rb index 0deb6ab417..df30890c18 100644 --- a/app/components/primer/truncate.rb +++ b/app/components/primer/truncate.rb @@ -3,7 +3,7 @@ module Primer # Use `Truncate` to shorten overflowing text with an ellipsis. class Truncate < Primer::Component - status :beta + status :deprecated DEFAULT_TAG = :div TAG_OPTIONS = [DEFAULT_TAG, :span, :p, :strong].freeze diff --git a/docs/content/guides/primer_local_time.md b/docs/content/guides/primer_local_time.md index 198602b6db..851b678fcc 100644 --- a/docs/content/guides/primer_local_time.md +++ b/docs/content/guides/primer_local_time.md @@ -18,7 +18,8 @@ For example, if the `LocalTime` was set up in this way: <%= 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"`. +It can be migrated by removing `initial_text`, setting an empty `prefix`, and +adding `threshold: "PT0S"`. ```rb <%= Primer::Beta::RelativeTime(datetime: Time.now, prefix: "", threshold: "PT0S") %> diff --git a/docs/content/guides/primer_time_ago.md b/docs/content/guides/primer_time_ago.md index 9dec7616c1..86a7b7c27f 100644 --- a/docs/content/guides/primer_time_ago.md +++ b/docs/content/guides/primer_time_ago.md @@ -36,8 +36,8 @@ noted, however. | `micro` | `format: :micro` | Instead of a boolean flag, set the `format` argument to the value of `:micro` | | n/a | `tense: :past` | Required for displaying how long ago the set time was. This argument tells `RelativeTime` to behave like `TimeAgo` did. | -The remaining arguments for `RelativeTime` can be found in the docu7mentation -for that component. +The remaining arguments for `RelativeTime` can be found in the documentation for +that component. Please see the following for complete descriptions and examples. diff --git a/docs/content/guides/primer_truncate.md b/docs/content/guides/primer_truncate.md new file mode 100644 index 0000000000..fe2d8b1263 --- /dev/null +++ b/docs/content/guides/primer_truncate.md @@ -0,0 +1,67 @@ +--- +title: Moving Away From `Primer::Truncate` +--- + +This guide will show you how to upgrade from the now-deprecated +[`Primer::Truncate`](https://primer.style/view-components/components/truncate) +to the latest +[`Primer::Beta::Truncate`](https://primer.style/view-components/components/beta/truncate) +component. + +The new `Truncate` component additionally now includes a text slot used for the +truncated text. + +## Some Migration Examples + +Migrating the most common use cases of the `Truncate` component simply requires +changing the name. + +Previously we might have something like: + +```ruby +<%= render(Primer::Truncate.new(tag: :p)) { "Some really, really verbose content" } %> +``` + +That's now: + +```ruby +<%= render(Primer::Beta::Truncate.new(tag: :p)) { "Some really, really verbose content" } %> +``` + +The `tag` argument now defaults to `:span` instead of `:div`, so if we want to +continue wrapping content in `
` tags we'll need to explicitly set that. So, +if we'd been using: + +```ruby +<%= render(Primer::Truncate.new) { "Some more very very long text" } %> +``` + +We can now equivalently write: + +```ruby +<%= render(Primer::Beta::Truncate.new(tag: :div)) { "Some more very very long text" } %> +``` + +## Arguments + +The following arguments for the component initializer have changed between the deprecated and newer versions +of the `Truncate` component. + +| From `Primer::Truncate` | To `Primer::Beta::Truncate` | Notes | +|-------------------------|-----------------------------|--------------------------------------------------------------------------| +| `tag` | `tag` | Previously defaulted to `:div`, now `:span`. | +| `inline` | n/a | Removed in `Primer::Beta::Truncate`. | +| n/a | `priority` | If `true`, the text will be given priority (by increasing `flex-basis`). | + +The remaining arguments for `Truncate` can be found in the documentation for +that component. + +Please see the following for complete descriptions and examples. + +* [Deprecated `Primer::Truncate`](https://primer.style/view-components/components/truncate) +* [`Primer::Beta::Truncate` component](https://primer.style/view-components/components/beta/truncate) +* [`Primer::Beta::Truncate` Lookbook examples](https://primer.style/view-components/lookbook/inspect/primer/beta/truncate/default) + +

 

+ +[← Back to migration guides](https://primer.style/view-components/migration) diff --git a/docs/content/migration.md b/docs/content/migration.md index c7befcea95..cc95258fc9 100644 --- a/docs/content/migration.md +++ b/docs/content/migration.md @@ -30,3 +30,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::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) | | [`Primer::TimeAgoComponent`](https://primer.style/view-components/components/timeago) | [`Primer::Beta::RelativeTime`](https://primer.style/view-components/components/beta/relativetime) | [Upgrade to Primer::Beta::RelativeTime](https://primer.style/view-components/guides/primer_time_ago) | +| [`Primer::Truncate`](https://primer.style/view-components/components/truncate) | [`Primer::Beta::Truncate`](https://primer.style/view-components/components/beta/truncate) | [Upgrade to Primer::Beta::Truncate](https://primer.style/view-components/guides/primer_truncate) | diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml index 87bec94cc8..e9cc1f514c 100644 --- a/docs/src/@primer/gatsby-theme-doctocat/nav.yml +++ b/docs/src/@primer/gatsby-theme-doctocat/nav.yml @@ -127,6 +127,8 @@ url: "/components/iconbutton" - title: Tooltip url: "/components/tooltip" + - title: Truncate + url: "/components/truncate" - title: Architecture decisions children: - title: Developing and publishing client-side behaviours diff --git a/lib/primer/deprecations.yml b/lib/primer/deprecations.yml index 5592c9c720..a563e0b884 100644 --- a/lib/primer/deprecations.yml +++ b/lib/primer/deprecations.yml @@ -33,3 +33,8 @@ deprecations: - component: "Primer::Tooltip" autocorrect: true replacement: "Primer::Alpha::Tooltip" + + - component: "Primer::Truncate" + autocorrect: false + replacement: "Primer::Beta::Truncate" + guide: "https://primer.style/view-components/guides/primer_truncate" diff --git a/static/arguments.json b/static/arguments.json index 97641895d9..8a24639470 100644 --- a/static/arguments.json +++ b/static/arguments.json @@ -1805,7 +1805,7 @@ }, { "component": "Truncate", - "status": "beta", + "status": "deprecated", "source": "https://github.com/primer/view_components/tree/main/app/components/primer/truncate.rb", "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/truncate/default/", "parameters": [ diff --git a/static/statuses.json b/static/statuses.json index 8ef3bd608f..e1c514fdcd 100644 --- a/static/statuses.json +++ b/static/statuses.json @@ -95,5 +95,5 @@ "Primer::LayoutComponent": "alpha", "Primer::Navigation::TabComponent": "deprecated", "Primer::Tooltip": "deprecated", - "Primer::Truncate": "beta" + "Primer::Truncate": "deprecated" }